[SeasonOfDocs] The template for a quickstart

[Felicity Brand]

Just an update: I'm not going to get to this any time soon, sorry. I have
interstate visitors at the moment, and I'll be travelling for a funeral
next week. I might get time from Thursday onwards. Apologies, I won't be
able to make our Wednesday meeting.
Clarence, if you want to start the google doc I can add my stuff to it
later. Otherwise if you're all happy to wait that's fine too.
Cheers
Felicity

On Sat, Aug 24, 2019 at 7:18 AM Cameron Shorter <cameron.shorter at gmail.com>
wrote:

> Google Doc works for me too.
> On 22/8/19 11:41 pm, Clarence Cromwell wrote:
>
> I'm in favor of a Google doc, so everyone can contribute or make comments.
>
> On Wed, Aug 21, 2019 at 11:47 PM Felicity Brand <felicitybrand at gmail.com>
> wrote:
>
>> Thanks Clarence! I think I had an action item on me to make a google doc
>> to get this started.
>>
>> What I can do is grab the ideas you've shared here, put them in a google
>> doc and add my ideas too...
>>
>> Or is there another way? Like, is a google doc the best way? Should I be
>> doing something in one of our github repos instead?
>>
>> Felicity
>>
>>
>> On Thu, Aug 22, 2019 at 2:11 PM Clarence Cromwell <
>> clarencewcromwell at gmail.com> wrote:
>>
>>> We have to start somewhere. If the quickstart is going to be our first
>>> template, here are some ideas to include in it. I will also look at
>>> examples of some of the quickstarts I've worked on to see if they give me
>>> any more ideas.
>>>
>>> Can anyone add to this?
>>>
>>> My ideas to contribute to a quickstart template.
>>>
>>> 1.) The main body should follow these guidelines.
>>>
>>> * It should be a clear, concise, step-by-step tutorial (A set of
>>> numbered steps)
>>> * It should describe the easiest way to use the API, as opposed to the
>>> most optimized production modes or most advanced uses
>>> * It should be explaining the basic operations that most users will want
>>> to perform on the site, or the operations they will perform first.
>>> * Each step should contain all the information necessary to complete it.
>>> And the Quickstart should not contain any additional info that is not
>>> needed--because it will be easier to understand if it is as brief as
>>> possible.
>>> * It should include code samples (examples) that users can copy and
>>> paste. For each step that the user has to perform. (If it's an API)
>>> * Each example should be explained in comments that follow directly
>>> after the example, so newcomers can quickly understand how the API works
>>>
>>> 2.) The quickstart should not include:
>>>
>>> * Setup information
>>> * Things that belong in the reference section, like authentication,
>>> throttling, error codes, a complete description of any feature.
>>> * Things that belong in the overview (a general description of the
>>> product; what it can do; what it can't do)
>>>
>>> 3.) Links to external examples. The quickstart template should include a
>>> list of examples of good quickstarts that you can check out for comparison.
>>> It should discuss what we like or don't like about each example.
>>>
>>>
>>>
>>> _______________________________________________
>>> SeasonOfDocs mailing list
>>> SeasonOfDocs at lists.osgeo.org
>>> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>>>
>>
> _______________________________________________
> SeasonOfDocs mailing listSeasonOfDocs at lists.osgeo.orghttps://lists.osgeo.org/mailman/listinfo/seasonofdocs
>
> --
> Cameron Shorter
> Technology Demystifier
> Open Technologies and Geospatial Consultant
>
> M +61 (0) 419 142 254
>
> _______________________________________________
> SeasonOfDocs mailing list
> SeasonOfDocs at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190824/016d5ad7/attachment.html>