[SeasonOfDocs] The template for a quickstart

[Cameron Shorter]

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 list
> SeasonOfDocs at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/seasonofdocs

-- 
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190824/2dc6cdcd/attachment.html>