firebird-docs

[Firebird-docs] Hi

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

Hi Paul,

Paul Vinkenoog wrote:

>>4. User Documentation
> 
> 
>>Although I wrote 2 books on Delphi (in Portuguese), I never tried to
>>write user documentation on a product as complex as Firebird, but I
>>think I can give it a try. The difference between this topic and the
>>3 previous ones is that, for user documentation, I think it would be
>>preferable for me to try to write some before saying that you can
>>count on me for that.
> 
> 
> Looking at the way you write I have a very strong feeling that you can
> do this. But surely you could try it out by first writing e.g. a small
> task-oriented doc.
> 
> Could you please have a look at this page to get an idea of what we're
> trying to do, and how:
> 
>   http://www.firebirdsql.org/index.php?op=devel&sub=doc
> 
> If you're interested to help, you can join the firebird-docs list -
> you'll find a link on the abovementioned page.


As you suggested, I subscribed to Firebird-docs. I'm willing to help, but I must
admit this is an approach to writting that I never used before.

Just 2 simple questions:

1. Is there any global TOC so that we can pick up a subject from what is missing?

2. Would you agree if I tried to write a simple test text and send it to you or
someone else just to check if I understood the way of working with docbook? (I
never used it before).

Regards

Armando Halpern

Re: [Firebird-docs] Hi

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

Hi Armando,

So you managed to subscribe after all? (I was just about to answer
your message in FFmembers when I saw this one appear).

> As you suggested, I subscribed to Firebird-docs. I'm willing to
> help, but I must admit this is an approach to writting that I never
> used before.

I was in the same situation when I joined the doc effort about 1,5
years ago. I'd never used DocBook and I really had to get used to it.
But I soon started to like it more and more.

> 1. Is there any global TOC so that we can pick up a subject from
> what is missing?

No, the TOC only contains the items that are really there. Anyway,
there have been some new developments during the last couple of days
that may lead to a change in our planning (certainly in mine):

- IBPhoenix are donating their QuickStart Guide to the project. This
  guide was already free, but (c) IBPhoenix. Author Helen Borrie is
  now writing an app to convert it to DocBook XML. Once that is done,
  we get the QSG in DocBook format and then it will be our job to
  update it to Firebird 1.5 and maintain it in the future. The
  QuickStart Guide is going to be part of the official Firebird
  release packages.

- Somewhere in the near future we'll also inherit the Using Firebird
  guide. This is a real monster so it'll give us a lot of work.

- IBPhoenix has an API Guide and an SQL Reference in the planning.
  These are *not* going to be free, but in light of our own situation
  (Michael Gloegl no time to work on SQL ref; myself barely started
  with API ref) it might be better to drop these items for now and
  work on other things: Reserved words list + Glossay, QuickStart
  Guide, Using Firebird... plus whatever other useful docs someone
  may come up with.


> 2. Would you agree if I tried to write a simple test text and send
> it to you or someone else just to check if I understood the way of
> working with docbook? (I never used it before).

Sure, you can send it to me. It doesn't even have to be a serious
Firebird-related text. Just try to use most of the basic elements:
chapter, sect1, sect2 (etc.), link, ulink, blockquote, emphasis,
filename, command, itemizedlist, orderedlist, variablelist,
programlisting, screen, note & friends, maybe a table... (see the
Docwriting Howto).

I do advise you to use XMLMind XML Editor, and then check the produced
DocBook source from time to time in a text editor (a disadvantage is
that you can't do that from within XXE). You can also write DocBook
XML directly in a text editor, but then you won't notice your mistakes
until you try to build a target.

Have you already checked out the existing docs from CVS? It may be
helpful to look at them as examples. The top document is
manual/src/docs/firebirddocs.xml, the individual docs are in
manual/src/docs/firebirddocs/*.xml


Greetings,
Paul Vinkenoog