[SeasonOfDocs] The template for a quickstart

[Felicity Brand]

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/fdaeff8f/attachment.html>