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
_______________________________________________
Live-demo mailing list
[email protected]
http://lists.osgeo.org/mailman/listinfo/live-demo
http://wiki.osgeo.org/wiki/Live_GIS_Disc
