[Firebird-docs] Re: [Firebird-devel] Documentation

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

I brought up the documentation issue in firebird-devel and the result =
was the issue has moved to the firebird-docs list at sourceforge.

I cannot get through to www.interbase2000.org so I can't check your =
reference.

I feel that Firebird documentation is seriously crippled and needs work. =
I hope to participate in creating a good documentation facility for it. =
I want to help create a "Reference Manual" slash "User's Manual" that is =
dynamic and inclusive.

The best documentation available for Firebird, the Beta Docs, are all =
tied up in copyright issues. Apparently Borland won't let us extend and =
update those docs to cover both InterBase and Firebird. If this is true, =
I will help document Firebird and let Borland pay for documenting =
InterBase.

What I wish for is not so much a printed manual as a web site where the =
divisions of the "manual" correspond to subtrees on the site.=20

The whole thing MUST be globally searchable; the second worst problem =
with Borland's documentation is that you have to figure out, on your =
own, where Borland stuffed the information. The worst thing about =
Borland's documenation is that we don't have any way to correct it when =
it's wrong.

Being a web site, this can not only can cover the material like a =
manual, but it can include links to other documents either here or on =
other systems - FAQ's, papers, various "Documentation" pages, etc. With =
a little effort it can be a reference library and not just a manual.

Being browser based, it can be burned into a CD-ROM.

There's talk that the source for this web site Firebird manual should be =
in the CVS tree at Firebird. That make sense to me. There's talk about =
it being in Docbook; I'll have a look at that.=20

Significantly, however, I want to get away from the classical model =
which is documenation professionals writing everything. There is so much =
work that we must go towards an open source model where anyone who knows =
something can check out the relevant portion of the 'manual', update it, =
and check it back in. The level of mandatory review is not yet clear.

To restate, what I want as a first cut is a web page user's manual tree =
of the topics, in name covering the material in the beta docs but in =
practice all the pages will be empty until somebody has the time to =
write them. There will probably be one higher level which functions as a =
documentation library, with one link into this web page user's manual =
tree.

If you, or anyone, can pry something loose from Borland it would help. =
Even the docs for InterBase 3 would be a help. If you want to work with =
me, if you want me to work with you, say the word. One way or another, =
we should do this on the Firebird-Docs list.

----- Original Message -----=20
From: "Joseph Alba" <ja...@il...>
To: <fir...@li...>
Sent: Monday, April 23, 2001 23:35
Subject: [Firebird-devel] Documentation


Hi to all Interbase newbies and devotees. This is Joseph Alba of the =
Interbase
documentation (see www.interbase2000.org). I would like to take your =
views on
how the Interbase documentation effort should begin, and how we should =
go about
it.

My goal is to have a weekly beta on the documentation. All who want to
contribute and comment are invited to write me privately at my email =
address
ja...@il...

As I mentioned to Helen, my experience as an independent developer makes =
me
careful about job specification, scope, and definition. I would like to =
deliver
a documentation set that is NOT an exhaustive tome of Interbase, but =
rather,
what Interbase users would want and need.

So, all suggestions and comments are welcome and needed. Please help. =
And please
reply in private to my email address

Thanks,

Joseph Alba
ja...@il...