You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@etch.apache.org by Michael Fitzner <Mi...@bmw-carit.de> on 2010/11/15 16:54:17 UTC
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
RE: Proposal Etch documentation for PDF and Html
Posted by "Youngjin Park (youngjpa)" <yo...@cisco.com>.
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
AW: Proposal Etch documentation for PDF and Html
Posted by Michael Fitzner <Mi...@bmw-carit.de>.
Hi James,
Thanks for your feedback and constructive suggestions. Some notes from my side, see below.
-----Ursprüngliche Nachricht-----
Von: James Dixson [mailto:dixson3@gmail.com]
Gesendet: Mittwoch, 17. November 2010 21:14
An: etch-dev@incubator.apache.org
Betreff: Re: Proposal Etch documentation for PDF and Html
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?
M: I think both factors are important and should be addressed. At the beginning it would be great if we have a clean document structure that we can fill with content afterwards. (etc. some of the Confluence documentation below http://incubator.apache.org/etch/documentation.html)
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.
M: Sounds great; you are kindly welcome in supporting documentation.
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.
M: Writing documentation in a XML based style (like DocBook) is surely not so comfortable like writing it with Word or other WYSIWYG editors. But I think big documentations like Ubuntu, the Linux Kernel, KDE shows also that this kind of documentation has some advantages in a distributed environment. Furthermore XML documents can be handle with SVN nearly perfect.
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.
M: I like your suggestion to start a pilot for an example document and all expected content elements. We could do this in two steps; the first one would be the integration into the build, the second one in creating an example document. I would like to see the pilot in the trunk to check also the Apache infrastructure like the Hudson Build-Servers. Afterwards we can check whether it is the the right document format.
M: Regarding the amount of documents, I think we don't need various documents. The primary document should be a consistent Etch manual. This document should consist of some chapters and sections and give you a general overview of Etch as well as details about each binding. The following structure is a proposal from my side:
Chapter 1:
Introduction
- About Etch
- Typographical Conventions
- About Code Examples
- Etch Contacts
- Etch Support
Chapter 2:
Overview
- Chapter overview
- Architecture
- Etch Components
- Facilities
Chapter 3:
Hello World Example
- Network Service Definition Language
- Binding Java
- Binding C#
- Binding C
- Binding C++
- Binding xyz
Chapter 4:
Network Service Definition Language
- Introduction
- Syntax Elements
- Compiler
- Source Files
- Data Types
- Language Annotations
- Source Documentation
Chapter 5:
Binding Java
- Introduction
- Data Type Mapping
- Generated Files
- Client
- Server
Chapter 6:
Binding C#
- Introduction
- Data Type Mapping
- Generated Files
- Client
- Server
Chapter 7:
Binding C
- Introduction
- Data Type Mapping
- Generated Files
- Client
- Server
Appendix I:
Bibliography
Wire Protocol
SSL Communication
Filters
- Keep Alive
- PwAuth
- Logger
Wireshark Support
Thanks
Michael
--
james
* Michael Fitzner <Mi...@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
>
Re: Proposal Etch documentation for PDF and Html
Posted by James Dixson <di...@gmail.com>.
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 <Mi...@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
>
Re: Proposal Etch documentation for PDF and Html
Posted by scott comer <we...@mac.com>.
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
>
>
AW: Proposal Etch documentation for PDF and Html
Posted by Michael Fitzner <Mi...@bmw-carit.de>.
Hi Martijn,
Thanks for the information about the new Apache CMS approach. For our website publications, I think it would be perfect and we should also migrate to it as soon as the CMS will be available to incubator projects. For the technical documentation (manual style), I would prefere a book like document structure, where you can generate PDF and Html output. This means that all the website publications like release note, download info, mailing lists etc. could be done with Apache CMS and the technical documentation (NSDL, Bindings, Compiler) with docbook.
Do you know about other Apache projects that use the CMS for manual styled documentation (PDF, Html)?
Michael
-----Ursprüngliche Nachricht-----
Von: Martijn Dashorst [mailto:martijn.dashorst@gmail.com]
Gesendet: Montag, 15. November 2010 21:01
An: etch-dev@incubator.apache.org
Betreff: Re: Proposal Etch documentation for PDF and Html
Please read http://www.apache.org/dev/cms.html if you are looking for
alternatives to confluence.
You are free of course to choose any documentation standard you wish,
in my experience writing XML really is painful. The Apache CMS uses
markdown as their templating language, and that is much better suited
for writing content than XML.
Note that infrastructure probably will move everyone away from
confluence (at least for the website maintenance) in due time. I'm not
sure if infrastructure will come up with an alternative to confluence
for the wiki part.
Martijn
On Mon, Nov 15, 2010 at 4:54 PM, Michael Fitzner
<Mi...@bmw-carit.de> 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
>
>
--
Become a Wicket expert, learn from the best: http://wicketinaction.com
Re: Proposal Etch documentation for PDF and Html
Posted by Martijn Dashorst <ma...@gmail.com>.
Please read http://www.apache.org/dev/cms.html if you are looking for
alternatives to confluence.
You are free of course to choose any documentation standard you wish,
in my experience writing XML really is painful. The Apache CMS uses
markdown as their templating language, and that is much better suited
for writing content than XML.
Note that infrastructure probably will move everyone away from
confluence (at least for the website maintenance) in due time. I'm not
sure if infrastructure will come up with an alternative to confluence
for the wiki part.
Martijn
On Mon, Nov 15, 2010 at 4:54 PM, Michael Fitzner
<Mi...@bmw-carit.de> 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
>
>
--
Become a Wicket expert, learn from the best: http://wicketinaction.com