[Live-demo] Documentation

Wed Mar 10 17:36:46 PST 2010

Hello,
In case you didn't know, in RC4 there are lots of bad links like this:

file:///usr/.../live-dvd/docs/http://grass.osgeo.org

instead of 

http://grass.osgeo.org

Regards,
Juan Lucas

--- On Mon, 3/8/10, Cameron Shorter <cameron.shorter at gmail.com> wrote:

> From: Cameron Shorter <cameron.shorter at gmail.com>
> Subject: Re: [Live-demo] Documentation
> To: "Hamish" <hamish_b at yahoo.com>
> Cc: live-demo at lists.osgeo.org
> Date: Monday, March 8, 2010, 9:50 PM
> 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
> 
> _______________________________________________
> Live-demo mailing list
> Live-demo at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/live-demo
> http://wiki.osgeo.org/wiki/Live_GIS_Disc
> 