Re: [Firebird-docs] Reference doc - Efficiency of work

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

Ivan Prenosil wrote:

> Generally, lot of work can be done either
> when many people contribute, each one a little, or
> when just couple of people contribute, of course each one a lot.
>
> The first option is probably the only one usable with free project,
> but it has too many drawbacks.
> 
> * Inefficient work (...)
> * Uneven quality (...)
> * Unpredictability (...)

> But it seems there are not much possibilities how to solve all this, is it ?

Not really, no. But at the moment those "many people" are hypothetical anyway.

> * Motivation - it can be influenced by many factors (sometimes seemingly
> unimportant), e.g.
>
> - contributors would also like to use resulting product, so they may hesitate
>   if it does not look as what they want. (e.g. I do not like HTML reference
>   much, since on Windows there are better formats)

I don't think a well-organised set of HTML pages - especially when there is
a navigation frame on the left - is worse than an old-style Windows Help file.
E.g. the documentation at www.php.net, which I use a lot, is very navigable.
The MySQL online SQL reference is worse (presentation-wise), but I still
wish we had *that* instead of our current nothing.

> - easiness of start - normally when I want to use new program, either I just
>   run it, or first install it and then run it. But the description of steps
>   needed to start with DocBook spreads several pages, which can be very
>   intimidating, because it quite often indicates that program authors are not
>   much good and that effort to start using such product can possibly take
>   several hours (or days). Yes, it finally took less than two hours and there
>   were no problems, but I can't know it in the moment of start !
>   Could it be possible to add red note on first page with time estimation, e.g.
>     "Installation is easy, if you will read and follow all instructions, it
>     will take approx. 1 to 2 hours."

Which installation are you talking about here? Of the CVS client and build tools,
i.e. what is discussed in the Docbuilding Howto? Or the XML and DocBook primers
(plus what follows) in the Docwriting Guide?


Paul Vinkenoog