Re: [college] Documentation Standard?

[Emmanuel Cecchet <emmanuel.cecchet@xxxxxxxxxxxxxxxx>]

Hi all,

I forward this thread on the architecture mailing list to have the input 
from the community.
As a first answer, I would strongly suggest that all proprietary formats 
from commercial tools such as Word are banished for our open source 
projects.
DocBook is a nice format but as David points out there is currently no 
good and free editor for DocBook. Please let us know if you know one !
Recently, we used OpenOffice for all tutorials and howtos in C-JDBC, 
that eases contributions and writing docs since XML is very tedious 
without an appropriate editor.

Don't hesitate to share your experience here,
Emmanuel

David Li wrote:

> Hi,
>
>   I think this fall under college discussion. Should we have a 
> recommendation on the documentation format standard for ObjectWeb 
> projects. While doing Chinese translation, we found that there are 
> several formats used: JOnAS is using HTML, Enhydra is in Words. Both 
> make the change tracking difficult, especially the translation 
> tracking. One thing we found that it's much easier to find initial 
> translators for documents but hard to find people to maintain the 
> translation up to date. Mostly because the effort needed in tracking 
> the change.
>
>   I'd like to bring up some potential solution on this:
>
> 1. DocBook seems to be good standard. However, the editor for it is a 
> bit lacking unless you are using emcas. ;)
>
> 2. There is XLIFF (XML Localisation  Interchange File Format) to 
> argument XML based DocBook
>
> http://www.xml.com/pub/a/2004/01/07/xmltm.html
>
> 3. There are some computer translation aid tools in open source that 
> support translation memory.
>
> http://www.omegat.org/ (Java based)
>
> I think it would a good idea to put together some 
> recommendation/guideline of documentation for projects under ObjectWeb.
>
> I am planning on doing some experiment with XMLC document. I am 
> wondering if others may be interested in join this.
>
> David
>
>
> ------------------------------------------------------------------------
>
>
>  


--
Emmanuel Cecchet

Principal architect              | Chief Architect
Java technologies, Emic Networks | ObjectWeb Consortium
http://www.emicnetworks.com      | http://www.objectweb.org