Re: [architecture] Documentation Standard Requirements

[claus.hirth@xxxxxxxxxxxxxx]

David Li <taweili@xxxxxxxxx> wrote on 15.02.2005
01:46:56:

> I agree that it's too early to call for adapting a standard on 
> ObjectWeb's documentation. 

> Moreover, it's probably not the 
> responsibility ObjectWeb to even call for a standard on project 
> documentations as it's not the objective of the consortium.

not a responsibility ...

> 
> The requirement for document standards comes from practical cooperation
> between projects. 

... but a practical requirement.

> The discussion started from my experience with
> Chinese project that translated ObjectWeb document into Chinese. There
> is also a Japanese project underway. One practical problem we are
> facing is the difficulty of maintaining the translated documents 
> up-to-date with the latest official document. Why? The formats such
as 
> Word or HTML are difficult to properly create delta (diff) so most
> likely the translators have to manually inspect the entire documents
> for change. Well, that gets to be very boring and tedious. 

Exactly.

> We are not really "deciding" on a format standard; it would
at best be 
> a recommendation and it's up for project team to make their own 
> decision whether to use it or not. There is no mean of enforcing a
> standard in the organization.

Also agreed. 

> 
> The basic list of requirements layout from the first post on document
> format is:
> 
> 1. open format
> 2. easy to generate diff
> 3. support for translation maintenance
> 
> Also, I agree that it's also important to consider easiness of 
> maintenance of the documents and tool support.

ok.

> Gathering from the discussion, I guess semantic based XML format is
a 
> rough consensus.

Possibly.

I would like to share three more requirements here:

(1)

The documentation format and tools must allow relieving
developers
from doing secretary work. Therefore I would want
to be able to 
include scans of handwritten notes as a developer,
have a secretary 
type it up, have a technical writer work on the wording,
translators
to translate it to different languages, and have the
result reviewed 
by myself and possibly others.

It is obviously not a trivial task to make such a
process work.
What we need is sort of a "DocForge" Web
Application, plus possibly 
more tools that can be executed locally.

It should be easy and beneficial to comply with a
documentation 
standard, otherwise it won't be widely adopted, and
project
interaction doesn't benefit. 

(2)

The solution must be better in terms of covered requirements
than TEX.

This brings us to the question what the requirements
are that are
covered better by DocBook than by TEX.

(3)

There must be at least one output format that allows
for
integrating personal notes into a personal copy of
the
documentation.

Currently I am using Adobe Acrobat to put sticky notes
on standard documents I read.

Kind regards

        Claus