Hi James, Thanks for your feedback and constructive suggestions. Some notes from my side, see below.
-----Ursprüngliche Nachricht----- Von: James Dixson [mailto:[email protected]] Gesendet: Mittwoch, 17. November 2010 21:14 An: [email protected] 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 <[email protected]> [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 >
