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

[Sunburned Surveyor]

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