[Live-demo] Getting OSGeo-Live Quickstart writing guidelines right

[Jody Garnett]

Cameron a few of your suggestions (such as linking to external content) directly conflict with use of the dvd and a machine not connected to the internet (which given the trouble with wireless at conferences was a common occurrence).

I recommend you define a substitution of some sort; so that links to material can be processed into a local reference for dvd use; and an external reference when placed on your website. Perhaps the same approach can be used to make images easier to handle?

Sphinx does have a :download:`path/to/resource` directive which is great for including stuff in the documentation. It will untangle relative paths and grab a copy into the docs. Perhaps if this approach was used; and then a script used to replace the targets with a symbolic link on the dvd (to prevent duplication of pdf files?)

-- 
Jody Garnett


On Friday, 27 May 2011 at 9:07 AM, Cameron Shorter wrote:

>  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].
> 
>  In particular, I'd like to hear from:
>  1. Quickstart authors, who have used our existing template, to tell us what is good and what is not.
> 
>  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.
> 
>  [1] http://wiki.osgeo.org/wiki/Live_GIS_Add_Project#Application_Quick_Start
>  [2] http://live.osgeo.org/en/overview/overview.html
> 
>  Below are specific comments I've noticed after picking out things I like from authors of the current Quickstarts:
> 
> Referencing directories on OSGeo-Live
>  Our previous guidelines have been specific about getting an application working on OSGeo-Live, however our docs are also being published at http://live.osgeo.org
>  As such, I suggest that we make the docs usable without loading OSGeo-Live as well
>  What this means:
>  * Have http://localhost/data/... link to data directories. Also have osgeo-live data copied to http://live.osgeo.org/data/
>  * Docs to mention that you can download data from the data/ url.
> 
> Introduction
>  * "This quickstart describes how to ..."
>  This should be made into a heading, as per:
> http://live.osgeo.org/en/quickstart/gvsig_quickstart.html
> 
>  * We should add a Table of Contents, as per:
> http://adhoc.osgeo.osuosl.org/livedvd/docs/en/quickstart/udig_quickstart.html
> 
>  * For some quickstarts, it may be appropriate to add a "What you will need" heading.
> 
> Version:
>  We should include the OSGeo-Live version and Application version.
> 
> Images:
>  * 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).
>  This is done quite easily with the shutter (linux) or greenshot (windows) screenshot tools. I suggest that other quickstarts do this too.
> http://live.osgeo.org/en/quickstart/gvsig_quickstart.html
> 
>  * We haven't got screen shots of menu selection, it would be good to have someone provide these.
> 
> Writing Style:
>  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.
>  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 ...."
>  I'd like to encourage other quickstarts to follow this conversational style.
> 
> http://live.osgeo.org/en/quickstart/R_quickstart.html
> http://live.osgeo.org/en/quickstart/geoserver_quickstart.html
> 
> Reference Material:
>  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.
>  If we do keep it, we should reference via a http://localhost URL rather than via a /usr/local/... filename. (That way it can be referenced from http://live.osgeo.org/... as well)
> 
> OpenStreetMap:
>  * 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.
> 
> Data:
>  There seems to be some common datasets that we should be providing:
>  * GPX file(s) to be used in navigation examples (Prune, OSM Tools)
>  * Photos with GPS metadata? (Viking)
>  * A SLD stylesheet (Mapnik?)
>  * A local dataset (GeoMoose, ?)
> 
> Example OSGeo-Live Web Services:
>  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)
> 
> 
> -- 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 http://www.lisasoft.com 
> _______________________________________________
> Live-demo mailing list
> Live-demo at lists.osgeo.org (mailto:Live-demo at lists.osgeo.org)
> http://lists.osgeo.org/mailman/listinfo/live-demo
> http://wiki.osgeo.org/wiki/Live_GIS_Disc

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.osgeo.org/pipermail/live-demo/attachments/20110527/f9ec7600/attachment.html