[SeasonOfDocs] The template for a quickstart

[Clarence Cromwell]

These are good ideas, Stephanie.

I'll start a Google doc this weekend for the Quickstart template. I think
we should begin the discussion by going over the big items  -- sections or
kinds of content that need to be included in this template.



On Wed, Aug 28, 2019 at 9:33 PM Stephanie Blotner <sblotner59 at gmail.com>
wrote:

> 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
>
> _______________________________________________
> 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/20190829/04befd44/attachment.html>