[Firebird-docs] Re: Three Questions

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

A: As much as possible of this discussion should be fed through =
Firebird-docs, yes? Seems to me that people perceive Firebird-develop as =
development=3Dcoding, and don't want it cluttered up with documentation =
issues. But if you and I rely on direct e-mail we have no community.=20

B: We need to think about what source format. DocBook has been =
recommended; I read up on it last night and it's not bad but then again =
I haven't got it executing yet.

THREE QUESTIONS:

> 1. What do we want?
We want documentation for Firebird; available via the Internet, globally =
searchable, accurate, up to date, maintained. For me, appearance is =
secondary. Electronic version is critical, print version is secondary. I =
think of the term "User's Manual" but conceptually the target is =
everything you need to know about FB.

> 2. What do we have?
We have a number of very busy people who know everything, and a large =
number of people who know a little bit. We have pretty good =
documentation which we can't copy but we can read. We have very good =
articles about various "side" issues.

> 3. Can we do what we want with what we have?
Certainly. There's a critical speed/time trade-off; the more people we =
can suck into this engine the faster we'll get ofr the ground.

Because of the distributed nature of our knowledge, I think it's =
critical that we encourage Ann, Boris, Claudio, David, etc. to correct =
things without having to install any software or learn any conventions. =
The people who know the most are the most busy; we must find an =
efficient way to tap their brains.=20

> I'd like to do things the Linux way. If you want something, try =
starting it
> and send it to me.
I'm not familar with "the Linux way". I thought that the open source way =
was to create a pool and encourage people to contribute. But whatever.=20

A few days ago I volunteered to have the tin can tied to my ankle; now =
Joseph Alba has taken the tin can and tied it to his ankle. You're =
welcome to it. You will be the caretaker for the Firebird Documentation. =
When formatting issues are settled, please create the outline - source =
for editing and web site for reading. Then the rest of us will start =
filling in the stubs.

Is this a good plan? Is it how you see your role?

----- Original Message -----=20
From: "Joseph Alba" <ja...@il...>
To: "Andy Canfield" <an...@ad...>
Sent: Tuesday, April 24, 2001 22:11
Subject: Re: [Firebird-devel] Documentation

> Dear Andy,
> Thanks for your comments. Helen B. informed me that Doug has a lot of =
load
> right now, so, I should take up the cudgels for documentation.
> Right now, I'd like to be more specific with what must be achieved. I
> believe in the maxim that in any new undertaking, ask yourself 3 =
questions
> 1. What do we want?
> 2. What do we have?
> 3. Can we do what we want with what we have?
> What we have is a community of volunteers. Gleaned from your =
suggestions,
> among those what we want is are Reference Manuals and Users Guides =
that is
> not copyrighted by Borland. (Other suggestions are How To's collation,
> etc...)
> I'd like to do things the Linux way. If you want something, try =
starting it
> and send it to me. For the community, I will assume that you will not =
claim
> any intellectual rights to the product, and I will assume the right to
> correct and revise it and present it to the community for further
> corrections. Everything will be Open Source with Firebird Community =
having
> the last say. If somebody else wants to improve on it, they send me =
their
> revisions.
> I will have a website where you can download the beta docs. Really =
like the
> Linux Documentation way.
> So, Andy, if you have something in mind, start writing it and send it =
to me,
> so I can go over it and present it to the community.
> By the way, don't worry about my credentials. I was asked by Helen and =
Ann
> last year to play second fiddle to Doug. But now, they told me to get =
things
> going.
> Thanks a lot for your enthusiasm. I'm looking forward to your =
contribution.
> Have a great day!
> Joseph Alba