i like it. it was always a goal (where appropriate) to have
documentation derive from the source code somehow. certainly build,
usage, examples, etc.
On 11/15/2010 9:54 AM, Michael Fitzner wrote:
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
