Re: [Firebird-docs] A how-to on writing Firebird docs?

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

Hello,

> This message is intended for everybody who is planning or
> considering to help with the Firebird docs.
>
> As said earlier, practically everything will have to be written from
> scratch. Helen Borrie, who has lots of experience with doc writing,
> advised us to develop a how-to on writing Firebird docs.

I've received some reactions off-list, and they made clear that there
really are people who want to write docs, and that a how-to and/or
guidelines would be greatly appreciated.

So... let's make a how-to. What should go in it? My first, rough idea
looks something like this:

1. A how-to on getting the manual module to work, with:
   - getting and installing Java 2
   - getting and installing CVS
   - checking out the Firebird manual module
   - building the docs that are already there
   - what to do if things don't work

   This would be for people who are at least considering to write
   docs. If we make such a how-to and we think it's good, we should
   have it placed in the Files section at SourceFource, and ask
   IBPhoenix to place a link (or even place the entire how-to as a
   webpage). Otherwise, you would first have to install Java 2 and
   CVS, check out the manual module and build the docs in order to
   read how to accomplish the things you have just done :-)

   A lot of the above information is already out there somewhere - I
   can't find it on www.ibphoenix.com right now but maybe I didn't
   look in the right place - but it's scattered and outdated here and
   there. David Jencks wrote quite a bit of useful stuff; it's in the
   manual module.

2. A how-to for those who really _are_ going to write docs, with:
   - how to pick a subject and where to discuss/announce it
   - why we really want you to write DocBook XML
   - general as well as fbdocs-specific DocBook instructions + tips
   - how to structure your document
   - style guidelines/tips
   - how and where to ask for commit rights
   - dos and don'ts if you have received commit rights

Of course the two documents should refer to each other. If they turn
out really small, they might even be combined into one.

Again, these are just rough outlines as they come up in my head right
now, I'm not at all saying that it must be like this!


Looking forward to your comments,
Paul Vinkenoog