[SeasonOfDocs] The template for a quickstart

[Stephanie Blotner]

I'd like to also advocate that a quickstart template includes:

   - A brief description of the <thing your'e getting started with> and
   what you will accomplish with the quickstart (1-2 sentences in case someone
   stumbles across the page)
   - A link to a page that describes setup steps


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

> Clarence,
>
> This is a really good set of principles to start from. I'd add:
>
>
> * Each step should be accompanied by obvious guidance. This will typically
> include a screenshot and/or sample code.
>
> * There should be sufficient detail in each step for a reader to
> understand how to use the application without having to actually run the
> Quickstart. Techies assessing to viability of a product will often read
> Quickstarts to assess whether the product is a good fit.
>
> * Our template should specify best practices in creating screen shots.
> What screen resolution should you use? Should you zoom out? (Probably not).
> How much of the window should be screen shot? (Probably just the sub-window
> specific to this step). Should you enhance the screen shot? Eg: Add (1) -->
> (2) --> (3) ... over buttons. Or shade unimportant areas of the screen shot.
>
> * We should define expectation around length of the Quickstart, and
> distinguish how it is different to a Tutorial.
>
> * We should define the target audience of a quickstart. (Getting into the
> metadata about different document types here). I'd say the persona is
> typically a person new to this produce, but typically with background
> domain expertise. They are likely still deciding whether to use this
> product or not, or are starting a journey to learning more about this
> domain.
> On 22/8/19 2:11 pm, Clarence Cromwell 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 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
>


-- 
Stephanie Blotner
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190828/e8242780/attachment.html>