[SeasonOfDocs] The template for a quickstart

[Clarence Cromwell]

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
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190822/81103cca/attachment.html>