incubator-etch-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From James Dixson <dixs...@gmail.com>
Subject Re: Proposal Etch documentation for PDF and Html
Date Wed, 17 Nov 2010 20:13:44 GMT
I am supportive of the effort to improve documentation, however are you
trying to address a problem of authoring/typesetting technology or a lack of
content?

I agree the more/better content is desirable. I would even be willing to
signup to write a couple docs on topics I am familiar with and people
want.

However, changing the authoring technology is a different problem than
improving/expanding the content. It is not at all obvious
to me that the wiki is a roadblock to content.

Initially we did experiment with docbook/forrest as the documentation
tech before we open sourced Etch. I maintain the doc set in that form
for several months before abandoning it. The biggest problem was the 
lack of good tools for authoring. Writing documents directly in XML
(i.e. 'coding' documents) is really really hard. 

We decided on the wiki mostly for ease of content creation
(open collaboration was secondary). We decided on Confluence because it is
the best out there and Apache supported it.

Before just migrating to a new doc technology, I would suggest the
following:

 1) Get the toolchain fully integrated into the build. Making it an
 optional target/set of dependencies is important.

 2) Put together a document plan and get folks to signup. Rather than
 just porting the wiki content into some new technology, start by enumerating
 new documents that would be most appropriate to create with the new
 toolchain. This will allow the toolchain to be exercised a bit and any
 issues worked out before any mass conversion. Ideally the pilot docs
 should be representative of all the formatting/typesetting
 possibilities expected to be used, e.g. books, chapters, figures, diagrams,
 indexes. This will give the authors a real feel for the issues involved.

 --
 james


* Michael Fitzner <Michael.Fitzner@bmw-carit.de> [2010-11-15 16:54:17 +0100]:

> Hi guys,
> A major part of the Etch documentation takes place inside Confluence Wiki at the moment.
We see some disadvantages for doing so and would like to start to improve the Etch documentation.
Some points which we would like to address:
> 
> -One documentation base (XML)
> 
> -Providing different output formats like PDF for storing and printing, HTML for online
documentation
> 
> -Customization of output should be possible
> 
> -Continuous development of documentation and versioning of it (etc. with SVN)
> 
> -Release management for documentation
> 
> -Documentation-Patches that are easy to provide
> 
> -Distributed development of documentation
> 
> 
> Our proposal to fulfill all these requirements; is using the docbook (http://www.docbook.org/)
format and its default toolchain like xslt, fo etc.
> To give you an expression how it could looks like, we have created a Jira-Issue [ETCH-115<https://issues.apache.org/jira/browse/ETCH-115>]
with a basic docbook documentation skeleton for etch, a Makefile for creating PDF and HTML
output and some resources like xslt stylesheets. It is possible to recreate the documentation
on a linux based system (for windows some Makefile adjustments are still necessary, but it
should also work)
> 
> The complete Etch documentation could be stored inside SVN and all guys are able to work
on it and provide patches. When the documentation has reached a certain quality it would be
time to do an extract and publish this one to our website (HTML + PDF Version).
> 
> If we plan to change our Website to Apache Forrest in future, we will still able to process
the docbook format with Forrest (this is supported by Apache Forrest).
> 
> If all like it; we would start to add the documentation artifacts to SVN and begin writing
documentation. Feedback is welcome.
> 
> Thanks
> Michael
> 

Mime
View raw message