[Live-demo] Documentation

[Cameron Shorter]

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.
> [*] tip o'the day: What abiword does for format conversions on the command line,
> Inkscape also does for SVG to EPS graphics needs. very handy!
>
>
> For a flat-ASCII format, upon reflection Mediawiki markup will be a better choice
> than reStructured Text (which is nice, but perhaps yet-another thing to learn).
>   
I'm happy to encourage the use of MediaWiki for the development of some 
of the docs. In particular, the docs which will primarilly be edited by 
geeks.

But what might work even better is the use of Google Docs to develop our 
word based docs. Advantages are:
* Docs can be downloaded as Open Office, Word, HTML or PDF
* Docs can be edited online in the familar Word like format
* Images can be embedded
* Very low technical barrier of entry
* Google Docs tracks verion control for us
* We don't need to worry about taking up too much disk space

> Asking people to learn Wiki markup should not be so great a request**, we could
> primarily use our mediawiki instance as the docs home.  Mediawiki allows
> Special:Export which outputs it as simple XML which can then be fed to a wide
> assortment of filters to PDF, html, etc. Also, by adding "&printable=yes" to the
> wiki page URL you get a "printer friendly" version with the side panels etc
> stripped away; so in that way the install_docs.sh script could pull the HTML
> version directly from the web. (as has already started to happen)  For offline
> users it would be nice to ship copies of the wiki "how to install" pages on-disc
> too.
>
> printer friendly version example:
>  http://wiki.osgeo.org/index.php?title=Live_GIS_Disc_Quick_Start&printable=yes
>
> I imagine there are some more simple wiki controls lurking which will keep the
> hyperlinks unexpanded, etc., and just show the main document frame in pretty-
> form. If not, we could write a HTML page template that simply added a header
> and footer and floated a frame containing the printable html version mid-page.
>
>
> as for mediawiki->PDF, well 178 hits, pick one:
>   http://www.mediawiki.org/w/index.php?title=Special%3ASearch&search=pdf&go=Go
>
> this one in particular looks nice:
>   http://www.mediawiki.org/wiki/Extension:PDF_Writer
>
> example output using Wikipedia's entry for "Solar system":
>   http://upload.wikimedia.org/wikipedia/commons/9/93/Solar_system_final.pdf
>
>
>
> [**] educators will have at least used wikipedia so it shouldn't be that scary
> an interface for them. also as educators IMO they should be willing to learn this
> tech so they can teach it/with it. it's not like we'd be asking them to use vi. Wiki
> editing is a highly-reusable skill, and also adds to our helper pool for the
> administrative wiki side of the project. ;)
>
>
>   
>> Hamish raised concerns about storing binary files in svn.
>> How serious is this concern.
>>     
>
> - once something is checked into SVN, it never leaves. So binary files which
> change frequently chew up vast amounts of SVN server space even if the trunk
> file is not that big. Even minor typo fixes could mean an entire new copy of
> the file needs to be permanently added to the DB. For text files AFAIU
> internally it stores version diffs, and branches and tag clones are entirely
> virtual. So SVN is highly efficient for text files, but a bloated mess for
> binary files.
> Currently the .odt files are so tiny that the DB bloat factor isn't an issue.
> Once annotated screenshots begin to be added to them it gets bad though.
>
> - using binary files pretty much completely kills any efficient peer review,
> which in turn also harms group collaboration. (typos, bug fixes, minor updates,
> etc don't flow in from the casual bystanders checking out the diffs in svn
> or the trac's timeline)
>
>
>   
>> I think our primary requirement is that we make documentation writing
>> (which includes images) easy to create, which means we need to move
>> away from using HTML as our source format.
>>     
>
> I am all for low barriers to entry, but I don't want to believe that <b>
> for bold and <p> for paragraph break is really that hard for the average
> voter to pick up. The trick is to just get people to try :). IMO fear of
> the unknown is a bigger hurdle than the learning curve in this situation.
> ... and of course the world would be a better place if everyone went through
> the 15 minute LyX tutorial as it doesn't take long to see how amazing it is. :-)
>
>
> but for today's vote wrt long-term strategy I'll get behind Wikimedia +
> Extension:PDF_Writer and whatever &printable=yes+frame, Htmlbook, or simple
> sed script brute-chop method gives us nice HTML. 
>
>
> Hamish
>
>
>
>       
>   


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