I think that the first goal is to construct a hierarchy and implement it =
as a web page tree. I suggest a top-level which is "documentation" and =
would function as a sort of refreence library, be able to link to =
articles, different site's "documentation" pages, etc. One of those =
links is to "User's Manual" which would be comparable to the beta docs, =
perhaps a bit more extensive. The Manual itself would, of course, be =
organized as a web page tree rather than as a few massive files. The =
whole thing is designed to be used interactively, not downloaded, =
although for people in Thailand and Antarctica it would be nice to have =
a downloadable version.
The difference in the two levels is that "Manual" is supposed to be a =
coherent document, with standard formatting styles and great =
integration, whereas "Documentation" is more like a library, where every =
piece is different. So "Documentation" is very mush like the ibphoenix =
documentation page, although I don't know just what the standard is =
there for including and excluding. The Firebird documenation page, like =
a library, should strive to include everything, as long as it's not =
definitely wrong, regardless of how useful. Not everything, of course, =
needs to be on the front page; we could have an "obsolete" subsection =
pointing to the IB 3 docs, for example.
For the "Manual", here's a tentative outline:
* "What Can Firebird Do For You" - covers material relevant to a project =
planner in deciding whether or not to use Firebird. What we can do, what =
we can't do. Available extensions (IBObjects, Delphi, etc.).
* "How To Use This Manual" - should be read by anyone who wants to find =
something here.
* "An Introduction to Firebird" - Takes the newbie who knows some Excel =
and explains concepts and terminology.
* "Installation" - A general guide plus specific installation on each =
platform. Covers not only server machines but also client machines.
* "Getting Started" - ? How to get something on the screen. Probably =
substructured into subcompondents for API, ODBC, Delphi, etc.
* "Connections" - Everything you'd ever want to know about connections - =
users, roles, connection strings, etc.
* "The C Application Program Interface"
* "Firebird SQL Language Reference Manual"
* "Tools" - IBConsole, isql, gpre, gli, etc. Something on every piece we =
ship with the product, even if we say "This is Jim's favorite but nobody =
else ever uses it." (;>)
* "Release Notes" - A reasonable level of information on every release =
for every platform. The user may be running an old version; this will =
tell him about it and whether he should upgrade.
* "Bugs" - symptoms, work-arounds. If fixed, which release was it fixed =
in. Psuedo-bugs =3D things people are surprised by that aren't really =
bugs.
Of course, sections can be added later, and sections can be subdivided. =
Some of the material already exists, such as "Introduction to Firebird"; =
it just needs to be updated / integrated / reformatted. Material such as =
"SQL Language Reference" exists but can't be copied, and so has to be =
regenerated.
Given a set of pegs, people can hang things from them. Let's figure out =
what kind of pegs we want, and then get the pegs on the wall in a couple =
of weeks.=20
|
