Re: [Firebird-docs] Complete Language Reference

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

Hello Dmitry,

[Appendix A]

>> But... that's most of the language reference, the way I understand
>> it.
>
> Yes, without syntax basics, operators, predicates and built-in 
> functions. And it nearly means the overall content will have to
> grow twice in size.

Even without those subjects, this would be a *huge* appendix. If it
includes DDL, DML, Transaction control and PSQL, that's already almost
100 PDF pages in the 2.1 LangRef *Update*. In the full LangRef, it
might be anything between 200 and 400 pages. (In IBPhoenix's RefGuide,
it's a little over 200 pages. They have shorter pages than we, but a
lot of functionality has been added since then.)

> Correct, but I have no objections to renaming the "reference" to a
> "manual" ;-)

One thing I'm asking myself now: how much time do you have available?
Have you set a certain number of hours aside for this, during N months?

Because *if* we start such a big integrated guide, we'd better make
sure we finish it too. Otherwise it will be a huge waste of time.

[Separate Guide and Reference:]

> IMHO, the problem is that they will have a lot of information
> duplicated. Both would explain how to select from tables and insert
> into them, just from different angles. This is why I thought having
> them inside a single document.

There will be lots of overlap, but as you say: the angle is different.
A manual takes people by the hand and teaches them how to do things:
This is how you create a table. This is how you *fill* a table. Etc.

A reference is much dryer, to the point, exact, formal, and complete.
The user of a reference already knows what a table is, how to create
it and how to fill it (in short: he's an experienced database developer),
but he needs a document where he can look up the exact syntax, presence
or absence of certain features, etc.

As a user, I've always found it easier if these two documents were
clearly separated. If they were small enough, they could be in one
volume, but ours aren't going to be small.

Looking up at my bookshelves, I see my old Turbo C books. I remember
that when I started, I worked through (most of) the User's Guide and
had trouble with the Reference Guide because it didn't *explain*
anything: it just threw syntaxes and other abacadabra at you.
Later, I rarely touched the User's Guide and often consulted the Ref.

> Actually, we may complete the "reference" first and then come back
> to this question, if required.

I'd rather we settle this first. I don't want you to concede too
quickly "because I'm the boss here" :-)  (which I'm not really, BTW).

We probably both agree that we should create the documentation which:
1) is best for our users, and
2) can be produced in a reasonable amount of time.

If the average Firebird user is more or less like me, the answer to
(1) would be: separate user and reference guides. The total time
investment would probably be roughly equal to that for a combined
guide. An advantage would be that we could publish the first document
earlier. It would make sense if this was the Reference, because we
already have part of that available (in the LRU).

But... who says that the average user is like me in this respect?
I'd like to hear some more opinons, especially from Helen and Norman
(being experienced doccers), but maybe we should also take this
question to the admin list.

Of course, if it turns out that an integrated manual/reference is
better after all, we have to address point 2: how much time will
it take?

We can also turn things around: if an integrated guide would take
an amount of time that we both find unacceptable (for me, that
would roughly be: over a year), then we don't even have to ask
other people's opinions about this, and can go straight to the
question which manual/ref to produce first.

I'd better stop now, I'm really tired but I hope I have made myself
clear. And I'm sure we can make something good here, whatever it
turns out to be.


Cheers!
Paul Vinkenoog