Fwd: AW: [college] Documentation Standard?

[Alexandre Lefebvre <alexandre.lefebvre@xxxxxxxxxxxxxxxxxxxx>]

Begin forwarded message:

> From: "Madl Alfred" <A.Madl@xxxxxxxxxxx>
> Date: 7 February 2005 13:55:21 GMT+01:00
> To: "college objectweb" <college@xxxxxxxxxxxxx>
> Subject: RE: AW: [college] Documentation Standard?
>
> Hi !
>
> We like docbook for several reasons:
>
> It is XML, so a lot more "open" than Word or something like that.
>
> Docbook is a pure semantic schema instead of just layout information like
> in HTML.
>
> There are nice and customizable layout XSL transformations into PDF and
> HTML which can easily be integrated into Ant / Maven builds.
>
> We like the idea of a clean separation of content and layout/skin/format
> :-)
>
> As far as I know we use simple XML editors but there are already some
> specialized Docbook editor products available and OpenOffice also has some
> limited Docbook support.
>
> It is also important to know that there are 2 different flavours of
> Docbook:
>
> The full blown schema, mainly for big "real books".
>
> The lightweight "simplified" schema for "articles", which we use for our
> documentation purposes and would recommend to start with !
>
> So currently it may be still a little bit archaic to edit Docbook, but the
> principle advantages are worth the effort in our view.
>
> Greetings.
>
> Alfred
>
> -----Original Message-----
> From: David Li [mailto:taweili@xxxxxxxxx] 
> Sent: Montag, 07. Februar 2005 09:08
> To: Madl Alfred
> Cc: college objectweb
> Subject: Re: AW: [college] Documentation Standard?
>
> Care to share the experience using DocBook? What took do you use for 
> editing, styling and etc.
>
> Thanks.
>
> David
>
>
> On Feb 7, 2005, at 4:02 PM, Madl Alfred wrote:
>
> > Hi !
> >
> > Just want to say that all Enhydra projects are now using Docbook for
> > documentation. Maybe except the "Getting Started Guide" of Enhydra
> > Server :-)
> >
> > Greetings.
> >
> > Alfred
> >
> > -----Ursprüngliche Nachricht-----
> > Von: David Li [mailto:taweili@xxxxxxxxx]
> > Gesendet: Sonntag, 06. Februar 2005 17:58
> > An: college objectweb
> > Betreff: [college] Documentation Standard?
> >
> >
> > 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
--
Alexandre Lefebvre, R&D Unit Manager
France Telecom, Research & Development, MAPS/AMS
28 chemin du Vieux Chene - B.P. 98
38243 Meylan CEDEX - France
phone: +33 4 76 76 45 63 - fax: +33 4 76 76 45 57
email: alexandre.lefebvre@xxxxxxxxxxxxxxxxxxxx
email: alefebvr@xxxxxxx