[Live-demo] Creating OSgeo training material as part of the OSGeo Live DVD

[Cameron Shorter]

This thread started on the LiveDVD email list, and I'm including the 
Education list as there is significant cross over.

To summarise, Hamish and Alex have been pushing to have LiveDVD docs 
stored as HTML, while I've been pushing toward moving to a familiar 
WYSIWYG editor (Word or Open Office).

Hamish wrote:
> <ship>
> I agree. I'm still very much in favour of a few pages of HTML
> and wget'ing in full PDF tutorials & cookbooks, as it's the
> only efficient way to efficiently bulk manage, review, and
> update so many different docs. If it's not automated and
> efficient, we'll drown in the work.
>   
Yes, this is a valid concern, which caused me pain for the last 3.0 
release as I had to make some bulk edits for these docs manually.

And while I'm not fixated on moving to an OpenOffice format for docs, I 
still think we should be giving it serious consideration and I'll 
explain my reasoning:

Open Source in general, and OSGeo in particular has a bad track record 
in creating good documentation. In particular:
* If techies write the docs, then the docs are often not witten well, or 
not targeted at users effectively.
* There is little consistancy between documentation from different 
projects. Ie, docs are often project specific, and not holistic, which 
is what would be desired by users or students.

I have run into many educators (university or tertiary education 
professors or teachers) who are very excited by GeoSpatial Open Source 
and who would love to teach it and create training material, but they 
are not sure how to engage with the Open Source community. The educators 
are not familiar with the OSGeo software so would need help from techies 
to help write the material.

These trainers are used to creating quality training material, usually 
writing documentation in word format. Some might be techie enough to 
learn to write HTML docs or use a wiki, but when they have a deadline to 
create material, they will use the tool they are most familiar with. Ie, 
Word (or Open Office).

So we have two communities, which both have half the solution to create 
quality OSGeo documentation - Educators know how to write quality 
material targeted at training, and OSGeo programmers have the technical 
knowledge of the projects they work on.

What do we need to do to get these communities together? I'm confident 
we can use the same successful formula we used for the liveDVD. Ie, we 
define a skeleton for the end product, then ask all experts to fill in 
content for the parts they are familiar with. Then everyone is given the 
incentive "if you do a little work, you will get a huge reward, which 
you couldn't achieve by yourself".

For educators:
"If you create a documentation template, including matching against your 
training criteria, then we will get OSGeo experts to fill out draft 
training material for you, which will just require final cleaning up 
from you to create full course material. And as an added bonus, the 
training material will come with a LiveDVD which is continuously updated 
with the latest software, and links with the training material"

For OSGeo projects:
"If you flesh out training material in accordance with this provided 
skeleton, they we will ensure that it is rolled into an education 
package, and then used in training students in schools."

---
In order to make this happen,
We need to set down the guidelines, and the documentation build process.

And one of the key criteria is that there needs to be a low barrier of 
entry for all contributors. And to engage educators, I think that if we 
force educators to use wiki, or html editing, instead of Word or Open 
Office, then we will loose 80% of our potential writers.
Yes educators could use a wiki for writing text, but training material 
requires images and tables, and include boxes etc. And we don't want the 
educators to spend 80% of their time wrestling with wiki formatting.

Hence, I think it important to create source documentation in Word/Open 
Office format. From word format we can convert to HTML, PDF, Docbook etc.


-- 
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