<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <meta http-equiv="content-type" content="text/html;
      charset=ISO-8859-1">
  </head>
  <body text="#000000" bgcolor="#ffffff">
    OSGeo-Education people,<br>
    <br>
    We are about to review all Quickstarts on OSGeo-Live [1], and I'm
    very keen to get feedback from you people who have experience
    creating tutorial type material.<br>
    <br>
    I'm particularly keen to get our formula for these quickstarts
    right, as I see it as a basis that can be used in future for
    creating full length tutorials for all OSGeo type software.<br>
    <br>
    Could I please impose upon you to have a look over the Quickstarts,
    and note what is good or bad and how we should improve our writing
    guidelines.<br>
    <br>
    -------- Original Message --------
    <table class="moz-email-headers-table" border="0" cellpadding="0"
      cellspacing="0">
      <tbody>
        <tr>
          <th nowrap="nowrap" valign="BASELINE" align="RIGHT">Subject: </th>
          <td>Getting OSGeo-Live Quickstart writing guidelines right</td>
        </tr>
        <tr>
          <th nowrap="nowrap" valign="BASELINE" align="RIGHT">Date: </th>
          <td>Fri, 27 May 2011 09:07:05 +1000</td>
        </tr>
        <tr>
          <th nowrap="nowrap" valign="BASELINE" align="RIGHT">From: </th>
          <td>Cameron Shorter <a class="moz-txt-link-rfc2396E" href="mailto:cameron.shorter@gmail.com">&lt;cameron.shorter@gmail.com&gt;</a></td>
        </tr>
        <tr>
          <th nowrap="nowrap" valign="BASELINE" align="RIGHT">To: </th>
          <td><a class="moz-txt-link-abbreviated" href="mailto:live-demo@lists.osgeo.org">live-demo@lists.osgeo.org</a>
            <a class="moz-txt-link-rfc2396E" href="mailto:live-demo@lists.osgeo.org">&lt;live-demo@lists.osgeo.org&gt;</a></td>
        </tr>
      </tbody>
    </table>
    <br>
    <br>
    <meta http-equiv="content-type" content="text/html;
      charset=ISO-8859-1">
    I'm looking for feedback on how we can improve the OSGeo-Live
    Quickstart writing guidelines [1] before we provide a comprehensive
    review of all Quickstarts [2].<br>
    <br>
    In particular, I'd like to hear from:<br>
    1. Quickstart authors, who have used our existing template, to tell
    us what is good and what is not.<br>
    <br>
    2. People from the OSGeo education community (who often are
    experienced in writing training material). I see these quickstarts
    as a stepping stone toward comprehensive OSGeo training material.<br>
    <br>
    [1] <a moz-do-not-send="true" class="moz-txt-link-freetext"
href="http://wiki.osgeo.org/wiki/Live_GIS_Add_Project#Application_Quick_Start">http://wiki.osgeo.org/wiki/Live_GIS_Add_Project#Application_Quick_Start</a><br>
    [2] <a moz-do-not-send="true" class="moz-txt-link-freetext"
      href="http://live.osgeo.org/en/overview/overview.html">http://live.osgeo.org/en/overview/overview.html</a><br>
    <br>
    Below are specific comments I've noticed after picking out things I
    like from authors of the current Quickstarts:<br>
    <br>
    <b>Referencing directories on OSGeo-Live</b><br>
    Our previous guidelines have been specific about getting an
    application working on OSGeo-Live, however our docs are also being
    published at <a moz-do-not-send="true"
      class="moz-txt-link-freetext" href="http://live.osgeo.org">http://live.osgeo.org</a><br>
    As such, I suggest that we make the docs usable without loading
    OSGeo-Live as well<br>
    What this means:<br>
    * Have <a moz-do-not-send="true" class="moz-txt-link-freetext"
      href="http://localhost/data/">http://localhost/data/</a>... link
    to data directories. Also have osgeo-live data copied to <a
      moz-do-not-send="true" class="moz-txt-link-freetext"
      href="http://live.osgeo.org/data/">http://live.osgeo.org/data/</a><br>
    * Docs to mention that you can download data from the data/ url.<br>
    <br>
    <b>Introduction</b><br>
    * "This quickstart describes how to ..."<br>
    This should be made into a heading, as per:<br>
    <a moz-do-not-send="true" class="moz-txt-link-freetext"
      href="http://live.osgeo.org/en/quickstart/gvsig_quickstart.html">http://live.osgeo.org/en/quickstart/gvsig_quickstart.html</a><br>
    <br>
    * We should add a Table of Contents, as per:<br>
    <a moz-do-not-send="true" class="moz-txt-link-freetext"
href="http://adhoc.osgeo.osuosl.org/livedvd/docs/en/quickstart/udig_quickstart.html">http://adhoc.osgeo.osuosl.org/livedvd/docs/en/quickstart/udig_quickstart.html</a><br>
    <br>
    * For some quickstarts, it may be appropriate to add a "What you
    will need" heading.<br>
    <br>
    <b>Version:</b><br>
    We should include the OSGeo-Live version and Application version.<br>
    <br>
    <b>Images:</b><br>
    * A few projects have provided informative drawing on top of screen
    shots, like including a [1] or [2] circle which matches steps, or
    draw a red ellipse around a button. (See the gvsig tutorial for
    numbers, geonetwork for ellipses).<br>
    This is done quite easily with the shutter (linux) or greenshot
    (windows) screenshot tools. I suggest that other quickstarts do this
    too.<br>
    <a moz-do-not-send="true" class="moz-txt-link-freetext"
      href="http://live.osgeo.org/en/quickstart/gvsig_quickstart.html">http://live.osgeo.org/en/quickstart/gvsig_quickstart.html</a><br>
    <br>
    * We haven't got screen shots of menu selection, it would be good to
    have someone provide these.<br>
    <br>
    <b>Writing Style:</b><br>
    I really like the writing style for the R and GeoServer quickstarts.
    Both make use of a friendly, conversational tone, similar to the way
    a tutor would talk to a class.<br>
    Eg: "Today we will ..., now that is a simple demo but what we'd
    really like is to ..., so lets try applying styling which will ...."<br>
    I'd like to encourage other quickstarts to follow this
    conversational style.<br>
    <br>
    <a moz-do-not-send="true" class="moz-txt-link-freetext"
      href="http://live.osgeo.org/en/quickstart/R_quickstart.html">http://live.osgeo.org/en/quickstart/R_quickstart.html</a><br>
    <a moz-do-not-send="true" class="moz-txt-link-freetext"
      href="http://live.osgeo.org/en/quickstart/geoserver_quickstart.html">http://live.osgeo.org/en/quickstart/geoserver_quickstart.html</a><br>
    <br>
    <b>Reference Material:</b><br>
    Some projects link to tutorial or reference material which has been
    copied onto OSGeo-Live. I suggest we remove this, and instead point
    at material on the external web.<br>
    If we do keep it, we should reference via a <a
      moz-do-not-send="true" class="moz-txt-link-freetext"
      href="http://localhost">http://localhost</a> URL rather than via a
    /usr/local/... filename. (That way it can be referenced from <a
      moz-do-not-send="true" class="moz-txt-link-freetext"
      href="http://live.osgeo.org/">http://live.osgeo.org/</a>... as
    well)<br>
    <br>
    <b>OpenStreetMap:</b><br>
    * There are a number of applications written up under
    OpenStreetMapTools. I'm included to suggest that they should be
    broken up with their own pages,? There are five of them plus Prune
    which is written separately.<br>
    <br>
    <b>Data:</b><br>
    There seems to be some common datasets that we should be providing:<br>
    * GPX file(s) to be used in navigation examples (Prune, OSM Tools)<br>
    * Photos with GPS metadata? (Viking)<br>
    * A SLD stylesheet (Mapnik?)<br>
    * A local dataset (GeoMoose, ?)<br>
    <br>
    <b>Example OSGeo-Live Web Services:</b><br>
    I wonder how hard it would be to set up a demo server with
    OSGeo-Live web services installed, such that external users to try
    it out. (This is not required for our documentation, but it would be
    a nice addition)<br>
    <br>
    <br>
    <pre class="moz-signature" cols="72">-- 
Cameron Shorter
Geospatial Director
Tel: +61 (0)2 8570 5050
Mob: +61 (0)419 142 254

Think Globally, Fix Locally
Geospatial Solutions enhanced with Open Standards and Open Source
<a moz-do-not-send="true" class="moz-txt-link-freetext" href="http://www.lisasoft.com">http://www.lisasoft.com</a>
</pre>
  </body>
</html>