[Live-demo] Documentation

[Alex Mandel]

Cameron Shorter wrote:
> Hamish,
> Some delayed responses to your thoughts below:
> 
> Hamish wrote:
>> Cameron wrote:
>>  
>>> However, it seems that the formatting doesn't come out very well.
>>> This may need some tweaking.
>>>     
>>
>>
>> Abiword is a neat tool*, but formatting issues are fundamentally
>> always going to
>> be the case unless a structured document format is used. Choice of
>> traditional
>> word processor isn't going to make any difference.
>>   
> I agree, we do need to be strict about ensuring that the template we use
> focuses on content, not styling, and that styling is applied after content.
>> If you want an editor which does the right thing, but is still
>> somewhat familiar
>> to openoffice/Words users, then LyX is it.
>>   
> I would love to agree with you, and went as far as writing a document
> processing tool for docbook formatted documents
> (http://generguide.sf.com) but later conceded that in order to engage
> the majority of users, you need to accept that 95% of users use MS Word.
> So we need to accept that people will create docs in MS Word, and then
> work out a processing chain for creating documentation from MS Word. (I
> think we can sometimes move people to Open Office from MS Word, but
> moving to LyX is too much of a jump).
> 
> I should point out that we have huge potential to migrate the greater
> community to OSGeo if we can attract Educators to make use of the
> LiveDVD. Educators will write training material based upon the LiveDVD
> if we make it easy for them, and they are by and large familar and
> committed to MS Word.

As I've said before - if this is the documentation goal I think the
basic docs should be html/source code non-binary and we should let
Educators submit links to any pdf or office format they have in the
Educational Inventory.

But this leaves 2 distinct types of material:
1. Live/Project maintained docs that tell the basics of what each
project is.
2. Education materials, sourced from various other places by links but
maintained by their authors and cataloged in the Educational Inventory.

So I'm in agreement with Hamish on the need to keep the svn materials in
text readable format, and would add that they should not exceed much
more than we already have. We should rather start a new section of the
script that pulls appropriate materials from the Edu Inventory just like
how I'm pulling the latest QGIS manual and linking it to the QGIS docs.

Thanks,
Alex