[Journal] My Thoughts On An OSGeo Documentation Tool Chain (Long Message)

[Dan Putler]

Has anyone looked at OSGeo journal/document preparation using LyX rather
than dealing with the straight LaTeX? This would give ease of use very
similar to a word processor (OO.o or MS Word?), but with the power and
portability of LaTeX.

Dan

On Fri, 2008-06-27 at 11:05 -0700, Sunburned Surveyor wrote:
> I want to share some of my thoughts about OSGeo the process and
> formats we will use for OSGeo documentation. This includes OSGeo
> educational material, but a lot of it might also apply to the OSGeo
> Journal.
> 
> Disclaimer: I am not a desktop publishing expert, nor am I a
> professional author. I don't intend to speak as an authority on this
> matter, but hope to offer some modest opinions and suggestions. I'm
> approaching this from the perspective of a new author that would like
> to be involved in the production of OSGeo documentation.
> 
> It looks like there are three (3) main "tool chains" to produce and
> manage technical documentation. There's the word processor tool chain,
> the LaTex tool chain, and professional desktop publishing tool chain.
> Let me share with you my thoughts on the advantages and disadvantages
> of each, and then I'll make a suggestion on how to move forward.
> 
> 
> Word Processor Tool Chain Advantages:
>    Familiar to most authors.
>    Easy styling.
>    Comes with spell check. :]
>    Export to PDF typically supported.
> 
> Word Processor Tool Chain Disadvantages:
>    Limited control of layout.
>    Layout of graphics can be awkward.
>    Limited support for mathematical formulas.
>    Mixes style and content.
>    Not exactly easy to search and index.
>    Export to other formats is limited.
> 
> LaTex Processor Tool Chain Advantages:
>    Familiar authors in the science and academic communities.
>    Great support for mathematical formulas.
>    Automated PDF generation.
>    Export to other formats is supported.
> 
> LaTex Processor Tool Chain Disadvantages:
>    The learning curve is very steep.
>    Freely available training material for authors is limited.
>    Installation of a complete LaTex system is a major chore.
>    Mixes style and content.
>    Not exactly easy to search and index.
> 
> Docbook Tool Chain Advantages:
>    Supported by existing XML tools.
>    Easy to search and index.
>    Format is extendable and can be customized for OSGeo needs without
> much effort.
>    Easy to learn. (I got up and running with Docbook in about a day.)
>    Clear separation of content and style.
> 
> Docbook Tool Chain Disadvantages
>    Requires the end-user know XSLT or CSS to produce documentation in
> a "human friendly" form.
>    No open source Docbook specific editor. (XML editors could be used.)
> 
> Professional Desktop Publishing Tool Chain Advantages:
>    Great control over layout, document appearance, and inclusion of graphics.
>    Production of "professional" and user friendly documents possible.
>    Easy to learn.
>    Supported by user-friendly open source tools.
> 
> Professional Desktop Publishing Tool Chain Disadvantages:
>    Limited support for mathematical formulas.
>    Mixes style and content.
>    Not exactly easy to search and index.
>    Export to other formats is limited.
> 
> I believe our choice of tool chain (or tool chains) will really depend
> on our goals.
> 
> If we want to produce professional and user-friendly documents
> suitable for printing and offline viewing then the desktop publishing
> tool chain would likely be the best choice.
> 	
> If we want to produce documentation that can be easily searched and
> cataloged, and also used to produce online documentation for a serious
> web presence, then I think Docbook would likely be the best choice.
> 
> If we want to embrace authors from the science or academic communities
> then LaTex seems to be the logical choice.
> 
> If we want ultimate ease of use for new authors, a word processor is a
> good option.
> 
> What is our goal with OSGeo documentation? Do we have a different goal
> for the Journal and the education material?
> 
> There are tool chain combinations that would also work well. For
> example, you could have most authors work in their favorite word
> processor and then have a dedicated team of OSGeo volunteers that
> cataloged the documentation and converted it to LaTex, Docbook, or PDF
> using one of the other tool chains.
> 
> I'd personally like to see us explore the use of Docbook as our main
> input format. I've been really impressed with what it can do.
> 
> I could write a simple GUI that used something like JDOM to convert
> Docbook to HTML. We could then come up with a CSS file to support a
> professional and "OSGeo" branded HTML layout. We could have one for
> use online, allowing a great Journal web presence, and one for
> printing. Once it was set in place, I think this system would work
> well.
> 
> I must admit that I have been really frustrated with LaTex, and I
> don't plan on investing the resources needed to learn it. That doesn't
> mean that we shouldn't use it as a group. If we do use it as our main
> tool chain, we should consider what framework we will use to support
> "non-latex" authors.
> 
> I know I've likely opened a can of worms, but I hope the discussion
> will help move us forward. I'm willing to begin work on a Docbook tool
> chain for OSGeo immediately if that is how we decide to move forward.
> 
> I'd also like to know what we might be doing in the area of search and
> catalogs for OSGeo material and web presence. Perhaps we set up some
> informal teams to tackle these two (2) issues and explore solutions?
> 
> I know that most major newspapers and magazines are concentrating on a
> heavy web presence. I think it makes sense to do so for the OSGeo
> Journal, and I think a Docbook tool chain could help get us there.
> 
> I look forward to hearing other's comments.
> 
> Landon
> _______________________________________________
> newsletter mailing list
> newsletter at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/newsletter
-- 
Dan Putler
Sauder School of Business
University of British Columbia