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

[Landon Blake]

Ned,

You wrote: "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."

This makes sense. I was a little unsure if LaTex was going to be our
official tool chain moving forward, so I was somewhat hesitant to
proceed on my own work until I cleared this up.

I think I will proceed with my two (2) current OSGeo projects, the
dictionary and the Free GIS Book using the docbook format with an HTML
version suitable for viewing and printing.

I'll send another post to the edu mailing list with some questions about
collaborating with other OSGeo authors on the Docbook tool chain.

Landon

-----Original Message-----
From: edu_discuss-bounces at lists.osgeo.org
[mailto:edu_discuss-bounces at lists.osgeo.org] On Behalf Of Ned Horning
Sent: Friday, June 27, 2008 12:42 PM
To: Sunburned Surveyor
Cc: edu_discuss at lists.osgeo.org; OSGeo Journal
Subject: Re: [OSGeo-Edu] My Thoughts On An OSGeo Documentation Tool
Chain(Long Message)

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
>
>   

_______________________________________________
Edu_discuss mailing list
Edu_discuss at lists.osgeo.org
http://lists.osgeo.org/mailman/listinfo/edu_discuss


Warning:
Information provided via electronic media is not guaranteed against defects including translation and transmission errors. If the reader is not the intended recipient, you are hereby notified that any dissemination, distribution or copying of this communication is strictly prohibited. If you have received this information in error, please notify the sender immediately.