<div dir="ltr">I'd like to also advocate that a quickstart template includes:<div><ul><li>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)<br></li><li>A link to a page that describes setup steps </li></ul></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Sat, Aug 24, 2019 at 3:54 AM Cameron Shorter <<a href="mailto:cameron.shorter@gmail.com">cameron.shorter@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
  
    
  
  <div bgcolor="#FFFFFF">
    <p>Clarence,</p>
    <p>This is a really good set of principles to start from. I'd add:</p>
    <p><br>
    </p>
    <p>* Each step should be accompanied by obvious guidance. This will
      typically include a screenshot and/or sample code.</p>
    <p>* 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.</p>
    <p>* 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.</p>
    <p>* We should define expectation around length of the Quickstart,
      and distinguish how it is different to a Tutorial.</p>
    <p>* 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.<br>
    </p>
    <div class="gmail-m_7868169264129668825moz-cite-prefix">On 22/8/19 2:11 pm, Clarence Cromwell
      wrote:<br>
    </div>
    <blockquote type="cite">
      
      <div dir="ltr">
        <div>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. </div>
        <div><br>
        </div>
        <div>Can anyone add to this?</div>
        <br>
        <div>My ideas to contribute to a quickstart template. </div>
        <div><br>
        </div>
        <div>1.) The main body should follow these guidelines.  </div>
        <div><br>
        </div>
        <div>* It should be a clear, concise, step-by-step tutorial (A
          set of numbered steps)</div>
        <div>* It should describe the easiest way to use the API, as
          opposed to the most optimized production modes or most
          advanced uses </div>
        <div>* It should be explaining the basic operations that most
          users will want to perform on the site, or the operations they
          will perform first. </div>
        <div>* 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. </div>
        <div>* 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)</div>
        <div>* Each example should be explained in comments that follow
          directly after the example, so newcomers can quickly
          understand how the API works </div>
        <div><br>
        </div>
        <div>2.) The quickstart should not include: <br>
        </div>
        <div><br>
        </div>
        <div>* Setup information</div>
        <div>* Things that belong in the reference section, like
          authentication, throttling, error codes, a complete
          description of any feature.</div>
        <div>* Things that belong in the overview (a general description
          of the product; what it can do; what it can't do)</div>
        <div><br>
        </div>
        <div>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. </div>
        <div><br>
        </div>
        <div><br>
        </div>
        <div><br>
        </div>
      </div>
      <br>
      <fieldset class="gmail-m_7868169264129668825mimeAttachmentHeader"></fieldset>
      <pre class="gmail-m_7868169264129668825moz-quote-pre">_______________________________________________
SeasonOfDocs mailing list
<a class="gmail-m_7868169264129668825moz-txt-link-abbreviated" href="mailto:SeasonOfDocs@lists.osgeo.org" target="_blank">SeasonOfDocs@lists.osgeo.org</a>
<a class="gmail-m_7868169264129668825moz-txt-link-freetext" href="https://lists.osgeo.org/mailman/listinfo/seasonofdocs" target="_blank">https://lists.osgeo.org/mailman/listinfo/seasonofdocs</a>
</pre>
    </blockquote>
    <pre class="gmail-m_7868169264129668825moz-signature" cols="72">-- 
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254</pre>
  </div>

_______________________________________________<br>
SeasonOfDocs mailing list<br>
<a href="mailto:SeasonOfDocs@lists.osgeo.org" target="_blank">SeasonOfDocs@lists.osgeo.org</a><br>
<a href="https://lists.osgeo.org/mailman/listinfo/seasonofdocs" rel="noreferrer" target="_blank">https://lists.osgeo.org/mailman/listinfo/seasonofdocs</a><br>
</blockquote></div><br clear="all"><div><br></div>-- <br><div dir="ltr" class="gmail_signature"><div dir="ltr"><div>Stephanie Blotner</div><div><br></div></div></div>