Re: [Firebird-docs] Docs Built with Ventura

[Paul V. <pa...@vi...>]

Hello Darcy,

> Think of it this way: the most poorly managed document system that
> still produces readable documents is better than the best managed
> document system that produces broken and non-user friendly
> document. Having spent years working at one of the worlds largest
> oil companies I can tell you that most of the documents were poorly
> managed (i.e. Excel = database, Word = desktop publishing system,
> Document Control System - None, Format Standard = Microsoft) but
> very accessible to the end user. Because the dumbest people could
> access the documents, the company was very successful.

What you say is true, but many companies have since discovered that
this unmanageability of documents is becoming a bigger and bigger
problem. In fact this is the most important reason why formats such as
DocBook - separating content from presentation - were developed, and
companies are now investing noticeable resources in converting their
documentation.

> We should probably concentrate on documenting Firebird as opposed to
> building the perfect doc system, even though that in itself is a
> worthy cause.

Sure, our main goal is to produce documentation. But to be able to do
that, and especially to keep them manageable, we must invest time in
the system too. The more we can automate the rendering, the better.
Everything that's not automated when it comes to e.g. the PDF
rendering will have to be done by hand *over and over again* - for
every new document, and for every new revision of every existing
document. That's why I don't mind investing time thinking about and
discussing the Ventura import you're working on. Because if this
works, and if we succeed in minimizing the handwork, the time invested
will pay itself back n-fold: we will have uncompromised DocBook
sources, clear and attractive HTML pages, *and* state-of-the-art
PDFs with minimal (ideally none at all) post-rendering correction
necessary.

In other words, by investing time in improving the rendering system
now, we will have more time later to concentrate on what it's all
about: writing docs.


Greetings,
Paul Vinkenoog