firebird-docs

[Firebird-docs] Where to start?

[Armando H. <arm...@ac...>]

Hi all,

I don't know how you have felt when you joined this list, but I feel a little
confused about where should I start, maybe because I usually prefer to organise
and plan things before starting do do them.

It occurs to me a possibility which I'm no sure if you agree with it: maybe I
could start with a TOC for the basic documentation so that we could discuss and
refine it. From my point of view, when you have a TOC signaling what's to be
done it's easier to choose what piece of documentation I would like to write next...

Regards

Armando Halpern

Re: [Firebird-docs] Where to start?

[Paul V. <pa...@vi...>]

Hi Armando,

> I don't know how you have felt when you joined this list, but I feel
> a little confused about where should I start, maybe because I
> usually prefer to organise and plan things before starting do do
> them.
>
> It occurs to me a possibility which I'm no sure if you agree with
> it: maybe I could start with a TOC for the basic documentation so
> that we could discuss and refine it. From my point of view, when you
> have a TOC signaling what's to be done it's easier to choose what
> piece of documentation I would like to write next...

We made a rather informal to-do list last summer. If you point your
newsreader to news.atkin.com you may still find it. If it's expired I
can repost it.

We could make an updated version of this list. When it comes to
picking tasks, let's not forget:

- The Quickstart Guide will be coming our way soon (if Helen survives
  the conversion but I guess she will ;-)), so we don't have to write
  a beginners's guide - we only have to update it.

- After that, we'll also inherit Using Firebird, This is a big one, my
  initial thought is that we should split it up in several docs.
  Anyway, this too is a lot of material we don't have to write anymore.

- IBPhoenix will produce an API Guide/Reference and an SQL Reference.
  That doesn't mean that we can't do the same, but it seems more
  logical to concentrate on other tasks. After all, both require a lot
  of work and the IBPhoenix docs may not be free, but at least they will
  be there.

- One existing project that could use input is the Glossary.


Greetings,
Paul Vinkenoog

Re: [Firebird-docs] Where to start?

[Armando H. <arm...@ac...>]

Hi Paul,

Paul Vinkenoog wrote:
> Hi Armando,
> 
> 
  > We made a rather informal to-do list last summer. If you point your
> newsreader to news.atkin.com you may still find it. If it's expired I
> can repost it.

I think the to-do list is what follows, but I'm not sure:

 > Why not take a look at PostgreSQL:
 > http://www.postgresql.org/docs/7.3/static/index.html
 > - A tutorial, great for newbies with databases in general and Firebird in
 > particular
 > - From the users point of view, DML, DDL
 > - From the admin point of view, setup, optimize, deploy
 > - Programmer Guide, API
 > - SQL Reference
 > - Developer Guide, also with infos for people willing to contribute to Fb
 >
 >
 >>For now, the free Borland IB6 beta docs are still very usable with
 >>Firebird, provided you also have the Release Notes etc. that come with
 >>the consecutive Firebird versions. But InterBase and Firebird _will_
 >>diverge more and more, so in a couple of years' time this is really
 >>going to be a problem.

Please confirm if I got the right one.

> 
> We could make an updated version of this list. When it comes to
> picking tasks, let's not forget:
> 
> - The Quickstart Guide will be coming our way soon (if Helen survives
>   the conversion but I guess she will ;-)), so we don't have to write
>   a beginners's guide - we only have to update it.

Strangely enough, one of my main concerns about Firebird Docs is beginner docs 
as I find hard to persuade people to try it without good documentation for 
beginners.

> 
> - After that, we'll also inherit Using Firebird, This is a big one, my
>   initial thought is that we should split it up in several docs.
>   Anyway, this too is a lot of material we don't have to write anymore.

I've got it and the reference from the IBPhoenix CD and found them quite useful. 
If there is already some sort of agreement with IBPhoenix on this subject, I 
could eventually start revising or updating it.

> 
> - IBPhoenix will produce an API Guide/Reference and an SQL Reference.
>   That doesn't mean that we can't do the same, but it seems more
>   logical to concentrate on other tasks. After all, both require a lot
>   of work and the IBPhoenix docs may not be free, but at least they will
>   be there.
> 
> - One existing project that could use input is the Glossary.

Sorry about this Paul, but I'll try to give some help outside the glossary 
project. That is not really the kind of area I would work on (I hate glossaries 
and glossaries hate me in return).

regards

Armando

Re: [Firebird-docs] Where to start?

[Paul V. <pa...@vi...>]

Hi Armando,

> I think the to-do list is what follows, but I'm not sure:
>
>> Why not take a look at PostgreSQL:
>> http://www.postgresql.org/docs/7.3/static/index.html
>> - A tutorial, great for newbies with databases in general 
>>   and Firebird in particular
>> - From the users point of view, DML, DDL
>> - From the admin point of view, setup, optimize, deploy
>> - Programmer Guide, API
>> - SQL Reference
>> - Developer Guide, also with infos for people willing to 
>>   contribute to Fb

> Please confirm if I got the right one.

Yes, that and a little list I posted earlier in that thread:

> - a DDL guide
> - a DML guide
> - an SQL reference
> - an API guide
> - a Programmer's Guide
> - ...
> - ...

But this was never worked out to something formal. Wouldn't have made
much sense, too, because at the time there was only Tilo and me and a
little later Tilo announced that he didn't have time to write docs
(he's active in the Marathon Project).

> Strangely enough, one of my main concerns about Firebird Docs is 
> beginner docs as I find hard to persuade people to try it without 
> good documentation for beginners.

Maybe you would like to work on updating the Quickstart Guide then?
And later on, (pieces of) Using Firebird.

But feel free to come up with something else.

>> - One existing project that could use input is the Glossary.
>
> Sorry about this Paul, but I'll try to give some help outside the 
> glossary project. That is not really the kind of area I would work 
> on (I hate glossaries and glossaries hate me in return).

OK, stay away from the Glossary - we don't want any bloodshed :-)


Greetings,
Paul Vinkenoog