incubator-etch-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael Fitzner <Michael.Fitz...@bmw-carit.de>
Subject AW: Proposal Etch documentation for PDF and Html
Date Mon, 29 Nov 2010 10:35:21 GMT
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 <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