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

[Ned Horning]

Landon,

Thanks for pulling this together. I'm not sure OSGeo Edu needs to adopt 
a single format/process for writing content for pretty much the same 
reasons you mention related to varied project goals. I am pretty much 
sold on using DocBook for my work and would be happy to help advocate 
the use of DocBook but in the end the decision might best be left to 
authors or projects. That would mean the we would need to figure out how 
best to catalog and provide search capabilities for varied formats but I 
expect that can be figured out.

Ned

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
> _______________________________________________
> Edu_discuss mailing list
> Edu_discuss at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/edu_discuss
>
>