[Firebird-docs] Documentation Site

[Andy C. <an...@ad...>]

embedded responses follow; as you read, keep in mind this example: the =
Beta docs and Borland's SqlRef.HLP file contain, as far as I know, the =
only existing specification of the SQL syntax accepted by Firebird.

----- Original Message -----=20
From: "Helen Borrie" <he...@di...>
To: <fir...@li...>
Sent: Friday, April 20, 2001 16:30
Subject: Re: [Firebird-devel] Firebird/InterBase Documentation Sources

At 03:46 PM 20-04-01 +0700, Andy Canfield wrote:
>I am working on documentation.
>[snip]
>What I look for as a first goal is a web page which references all =
documentation files, containing copies where possible or mere links =
where copyright problems arise. Such a documenation site would serve as =
a centralized Internet reference source but would not yet be searchable =
due to the variety of formats.

> Are you sure you are not reinventing the wheel? =20
> this resource already exists, at www.ibphoenix.com...

I believe you are referring to=20
    http://www.ibphoenix.com/ibp_document.html
IBPhoenix is a commercial organization, not the Firebird project. While =
the IBPhoenix people are dedicated to Firebird, the site is company, not =
community. No obvious way to contribute exists. No obvious way to search =
it exists. No obvious way to add my two cents to one of the pages.

I don't like the structure, personally. For example, try going to that =
web page and and find out the command-line parameters to gbak.exe. It's =
not searchable, there's no entry that says "Here is the documentation of =
gbak". At a second level there is a link to "the relevant person" if you =
want to code for gbak, even so the link points to a page that is =
effectively blank.

From http://www.ibphoenix.com/ibp_document.html I can't tell what is and =
what is not documented. It looks like a resource shop, not an =
interactive manual. In some sense, if I asked for the Firebird =
documentation and someone handed me     =
http://www.ibphoenix.com/ibp_document.html I would would feel as if I =
had not been handed the documentation, but a place from which I might =
obtain the documentation. The page is an excellent source of =
downloadable documentation but it is not the document itself. It looks =
like the Firebird version of amazon.com. What I am thinking about is =
more like a web-based version of the Beta docs, with better structure =
and links to anything that doesn't embed. What I hope to build is the =
user's manual. The closest thing we have to a user's manual is the Beta =
Docs.

Just as www.ibphoenix.com is not Firebird code, it's a place where you =
can find out where to obtain Firebird code, so too it is not the =
documenation (manual), it is a place where you can find the =
documentation.

> The final version of the IB6 docs exists already - it is ready to =
print. =20
> Unfortunately, it is not owned by Borland;  however, since it is a=20
> corrected and updated version of the existing beta docs,=20
> the owners cannot publish it without infringing Borland's copyright=20
> and giving Borland's lawyers their day in court.
It must be owned by someone! If Borland has copyright and XYZ updates it =
then Borland and XYZ have, in some sense, joint copyright, yes? Who is =
XYZ? Presumably employees of XYZ have the right to read it. Who owns the =
stock of XYZ? Even if I can't publish it, reading it would teach me more =
about Firebird so that I can write more accurate documentation. I keep =
thinking of the syntax of the CREATE VIEW command; if the Beta Docs are =
wrong on that, someone somewhere should have noticed and written a =
correction. It's a correction I need to read.

> This ever-so-slightly interesting piece of resource material=20
> was a casualty of the u-know-wot, nudge-nudge, wink-wink,=20
> not allowed to mention without getting flamed, events of last July.
In preparation for building a document, I am wandering over the =
burned-out ruin in the hopes of finding bits and pieces that can be =
useful, one way or another. That's all. I don't care about who set the =
fire (I have my opinions). I'm doing it for Firebird; not for Borland, =
not for Ashton-Tate, not for Inprise, not for IBPhoenix, much as I may =
respect some of the people there.

The closest thing we have to a user's manual is the Beta Docs - =
copyright someone else, we can't distribute them, we can't correct them, =
we can't extend them. Borland is under no obligation to continue to =
provide them as free downloads. As time goes on the Beta Docs will =
become more and more inaccurate; how do we deal with this?

> Are you sure you are not reinventing the wheel? =20
Sure I am. That's because the existing wheel is copyrighted. When James =
Watt invented the steam engine, the obvious way to use it was via a =
crank shaft. But the crank shaft was patented by someone else, so Watt's =
company had to use planetary gears. The existing documentation is =
scattered and the copyrights on it are even more scattered. I'm hoping =
to create a virtual manual that everyone can contribute to.