[Live-demo] Documentation

Fri Mar 12 11:38:04 PST 2010

Juan,
I think I've fixed these now. Thanks for picking this up.

Juan Lucas Domínguez Rubio wrote:
> 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
>>
>>     
>
>
>       
>   

-- 
Cameron Shorter
Geospatial Systems Architect
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