incubator-etch-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Youngjin Park (youngjpa)" <young...@cisco.com>
Subject RE: Proposal Etch documentation for PDF and Html
Date Mon, 15 Nov 2010 17:02:45 GMT
I like this. We finally have documents. Thanks. Youngjin

-----Original Message-----
From: Michael Fitzner [mailto:Michael.Fitzner@bmw-carit.de] 
Sent: Monday, November 15, 2010 7:54 AM
To: etch-dev@incubator.apache.org
Subject: Proposal Etch documentation for PDF and Html

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