[Firebird-docs] Re: Connections

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

----- Original Message -----=20
From: "Joseph Alba" <ja...@il...>
To: "Andy Canfield" <an...@ad...>
Sent: Thursday, April 26, 2001 22:09
Subject: Re: Connections


> Got your first copy.
>=20
> I like your common sense approach. There are a few technical things =
that
> need to be corrected and enumerated (like specify precisely what =
protocols
> are available.)
"All I know is what I read in the papers." (Beta docs)

> I would like to see a lot of examples: Step by step How to's
>=20
> Like:
>=20
> How to connect to an Interbase server using ISQL.
Can do.

> How to connect to an Interbase server using IBConsole.
Can do. With something like IBConsole, we need screen shots. Can do, but =
RTF format won't support them, so I'll have to send them in separately.

> How to test connections using IBConsole.
I don't quite follow you. As in test to see whether it's possible to =
connect to a database?

> (Mention also that IBConsole cannot connect to a Classic Linux server =
only
> SuperServer)
Will say.

> How to connect using Delphi BDE
I have no idea how; someone else will have to talk about this level.

> How to connect using Delphi Interbase Express (?)
I have no idea how; someone else will have to talk about this level.

> How to connect using Jason's IBObjects
I have no idea how; someone else will have to talk about this level.

> How to connect using API
Can do.

I don't want to get into too much detail. A firm example of each is OK, =
but... If the guy is using the API, I want to make sure that he reads =
the isc_attach_database() documentation which is elsewhere. I must, of =
course, include a link to it. Indeed, if we do the links right, we don't =
need to duplicate information because the user will wander wherever he =
needs to.  What I want to do is give him ideas and map the ideas into =
the specific commands without duplicating the effort of spelling out the =
specific commands.

For example, isc_attach_database() offers a whole raft of parameters =
besides user, role, etc. I don't want to cover any unless those are also =
permitted in other contexts. Apparently I need to add "cache", whatever =
that is, because it's in the SQL CONNECT statement.

> One thing I'd like the documentation to have is a lot of practical =
things. I
> believe in learning by example and doing.

A person needs to do but a person also needs to have the conceptual =
structure into which to map what he's doing. Here in Thailand people =
tend to memorize keystrokes; we don't want that. Also, the "Connections" =
section should be as complete as possible, even including things that =
are obscure, because if he's got a concern about a connection where else =
would he look? Examples are great, but, this is not a tutorial. If we =
write it write, many users won't need a tutorial. A tutorial walks you =
through the minimum; this tells you the maximum.

Good point, though. Ann mentioned "Now I've got it installed, what do I =
do?" This should include a link to a good tutorial that the person can =
read and walk through from his keyboard live.

> If a newbie were to read our docs, he should come out knowing HOW to =
do
> things, rather than lots of gobbledygooks without knowing HOW to do =
it. It
> would be a tragedy if the newbie knew about the Y-Valve or the =
difference
> between Classic and Superserver,  but not knowing HOW to connect.
Yeah. But in many cases, like running isql, much of the HOW is in a =
separate section, and should be linked here. This section is for the =
mind, not the fingers.

I will extend the examples, etc. but I don't want to get too far down =
the chain and duplicate stuff that ought to be in the other sections of =
the manual. Except for IBConsole, I would not want him to get the =
feeling that, having read this section, he doesn't need to read anything =
else. User expectation of a program like IBConsole is that he can play =
with it and learn by doing, not reading anything first. That's what I =
did; haven't read any IBConsole documentation yet. But for something =
like isql, he needs to read the documentation first, and that's the isql =
section, not just the Connection section.

> Would you like to give these how-to's a try?
As for isql, I hope to write it myself and therefore can experiment with =
the balance between the two. When we work out the guidelines for what =
goes in A and what goes in B, we can apply that division to A versus C =
and even X versus W.

ONE FIRM RULE (which I violated) - NO CODE OR COMMANDS SHOULD BE =
INCLUDED IN THE MANUAL UNLESS THEY HAVE BEEN TESTED, EXACTLY, VIA COPY =
AND PASTE. I have seen example C code in manuals where, if you feed it =
into a compiler as-is, it won't even compile. As you develop guidelines =
for documentation writers regarding style or subjects or whatever, =
please include this. Thanks.