Emmanuel Cecchet <emmanuel.cecchet@xxxxxxxxxxxxxxxx>
wrote on 07.02.2005 10:11:14:
> 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.
ok
> 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
!
No.
> Recently, we used OpenOffice for all tutorials and howtos in C-JDBC,
> that eases contributions and writing docs
OpenOffice is a practical choice. But is it good enough long term?
> since XML is very tedious
> without an appropriate editor.
I would like to drop a MUST requirement onto the table:
The documentation standard must make it very easy
for the reader providing feedback to refer to specific pieces
of specific editions of the document in question.
Editing or automated generation must be easy, too.
But I consider that less important than support for providing feedback.
Hm. I would like to write a proposal for a documentation standard and share my experience. Anyone of the industrial
members willing to donate money to finance 2 or 3
months of work?
>
> 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.
That would be perfectly well adressed by my proposal.
> >
> > 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.
Absolutely.
The ability to maintain documentation in a way that
brings them close to perfection over time is absolutely critical
to long term success.
Kind regards
Claus Hirth Diplom-Informatiker
Universität
> >
> > 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
>
>
>
> --
> You receive this message as a subscriber of the
> architecture@xxxxxxxxxxxxx mailing list.
> To unsubscribe: mailto:architecture-unsubscribe@xxxxxxxxxxxxx
> For general help: mailto:sympa@xxxxxxxxxxxxx?subject=help
> ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
