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

[Cameron Shorter]

Thanks Simon, valuable feedback as always.
Comments inline ...

On 31/05/2011 3:19 PM, Simon Cropper wrote:
> Cameron,
>
> 1) I tried over an extended period to become involved with creation of 
> tutorials for OSGeo and gvSIG community by found the 
> peculiar/particular ways of constructing documents were both time 
> consuming and frustrating. I imagine this is in part the cause for so 
> few new and on-going volunteers.

Yes, I've found programmers seem quite comfortable with our RST format 
we have chosen for our docs, but we haven't attracted many users, and 
some of the docs I've received, including a tech writer, sent the docs 
to me in word format, and I needed to convert.

I'd love to be introduced to a documentation creation process which 
makes this easier.

>
> 2) Rather than have developers create the documents, try and have 
> users create the documents as they have different perspectives.

I agree, but as yet found it hard to attract users. I've found that 
users often don't feel like they know enough to write the docs. Or 
possibly they are not as committed to their projects as the developers are.

>
> 3) Tutorials augmented with detailed and pertinent images make it easy 
> for the reader to follow what is going on. Extra time spent on an 
> image pays off big in comprehension (you need more than just a course 
> screen dump). Lines, numbering, highlights, boxes and annotations all 
> help direct a user's focus to those areas which are important.

Excellent point. I've cut and pasted the above into our writing guide at:
http://wiki.osgeo.org/wiki/Live_GIS_Add_Project#Screen_Shots

>
> 4) Once off documents are OK but maintenance of a document library is 
> the key to any good repository -- I don't think anyone has really 
> mastered this issue yet. You need to simplify the process for 
> contributors and people who create derivatives. No real idea how you 
> do this. No software is available that makes this easy.
>
> In regards to use of data...
>
> 1) Tutorials / Static documents should use the 1-2 standard datasets 
> you discussed.
>
> 2) Live demonstrations at the conference should endeavour to use local 
> datasets if suitable information is available. If possible these 
> 'workshops' or 'demos' should be captured as videos.
>


-- 
Cameron Shorter
Geospatial Solutions Manager
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