Re: [architecture] Documentation Standard Requirements

[David Li <taweili@xxxxxxxxx>]

>  > 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.

You have secretary!? I am jealous. ;) Just kidding.

I guess that's the workflow system. Maybe we could eventually build 
one. Would be great to have so we can also coordinate the activity on 
the document. I think the OIS (http://www.orbeon.com/software/) 
recently contributed to ObjectWeb has some capacity in this area.

> (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.

DocBook is purely semantic markup while TeX is a page layout language. 
I guess you mean LATeX which is roughly a semantic markup on top of 
TeX. Well, DocBook is XML and have more tool ready to process. Also, 
additional XML markup can be introduced into the document such as 
translation text and personal annotation to extend the document format. 
These shouldn't affect the XSL transforming the document.

> (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.

Well, DocBook is just a semantic markup language. It needs a XSL to 
render to a presentation format including PDF and HTML. You can still 
used the PDF version of manual.

David