<div dir="ltr">These are good ideas, Stephanie. <div><br></div><div>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. </div><div><br></div><div><br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Wed, Aug 28, 2019 at 9:33 PM Stephanie Blotner <<a href="mailto:sblotner59@gmail.com">sblotner59@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 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" target="_blank">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_5871428260173558091gmail-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_5871428260173558091gmail-m_7868169264129668825mimeAttachmentHeader"></fieldset>
<pre class="gmail-m_5871428260173558091gmail-m_7868169264129668825moz-quote-pre">_______________________________________________
SeasonOfDocs mailing list
<a class="gmail-m_5871428260173558091gmail-m_7868169264129668825moz-txt-link-abbreviated" href="mailto:SeasonOfDocs@lists.osgeo.org" target="_blank">SeasonOfDocs@lists.osgeo.org</a>
<a class="gmail-m_5871428260173558091gmail-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_5871428260173558091gmail-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-m_5871428260173558091gmail_signature"><div dir="ltr"><div>Stephanie Blotner</div><div><br></div></div></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>