Re: DOCBOOK: Modular Documentation

[camille <camille at mandrakesoft dot com>]

Hi Ed,

Ed Manley a écrit :
> 
> How can a company, no, how can I in particular, being completely naive to
> XML, best get started learning and implementing modular documentation in a
> small company?
[...]
> My idea is to take a small project (I am PM for perhaps 20 enhancements at
> any given time) and use that set of documents to teach myself how to do this
> and make a proof-of-concept for the company.
> 
> Can anyone here tell me how to approach this?

Wow...

I guess you've got two possible approaches:
1) rely on the tools provided by the companies you mentioned;
2) build your own system from scratch.

The pros and cons are obvious:
1) Reduced time to production but high cost, and limited control over
the system for custom uses and evolution;
2) the opposite of above statements, plus the need for technical skills
but the joys of working in a fast paced environment with a friendly
community ;-)

OK, my judgment is biased, as I do not know the first approach. 
For the second one, it took me one month to get the first results from
scratch); one year to get a really efficient document management system
in an environment similar to your; two years to make the system
available for the whole company.
This success story is probably common to most of the people here.

DocBook editing and compiling is now available out of the box for most
Linux distributions, and requires little work under Windows (I think).
All those tools are open-sourced and free, but WYSIWYG editors (which
anyway is heresy speaking about DocBook ;-). Though we are from nicely
integrated GUIs. If you are affraid to put your hands in grease, just
forget about it.

I'll now stress what Norman just told: there is a huge gap between
"traditional" technical documentation and DocBook way of life. It is a
completely different philosophy of writing which proves its benefits
only in the long term.

This is a good start:
http://www.oasis-open.org/docbook/documentation/faq/index.shtml

Good luck,

Camille.