Firebird Docwriting Guide

Paul Vinkenoog

25 Jan 2007 – Document version 1.2.2

Table of Contents

Introduction
Where the docmakers meet
Picking a subject
Preparing to write: make an outline!
DocBook XML – an introduction
DocBook XML authoring tools
Setting up your DocBook doc
Elements we use frequently
Language and style
Copyright issues
Adding your document to the manual module
A. Document History
B. License notice

Introduction

Purpose of this guide
Assumed knowledge
Topics discussed in this guide

Purpose of this guide

This guide discusses the various aspects of writing documentation for Firebird. It is intended for people who want to help write documentation for the Firebird project, or who at least strongly consider to do so. After reading this guide, you'll have all the necessary knowledge to start writing Firebird docs in our chosen format DocBook XML.

Assumed knowledge

Before reading this guide, check with yourself if you know:

What the Firebird manual module is.
What CVS is, and how to use a CVS client to download the current manual module.
How to build the current Firebird documentation from your downloaded manual module.

This knowledge is essential if you are going to contribute to our documentation project. If you feel unsure about one or more of these points, you should first read the Firebird Docbuilding Howto, and then come back here.

Topics discussed in this guide

We start off with some short chapters about:

The firebird-docs mailing list.
Picking a subject.
Making an outline for your document-to-be.

After that we'll take some time to explain the basics of DocBook XML, because that's the format we'd like you to deliver your docs in. Topics discussed include:

DocBook XML – what is it?
Reasons why we prefer DocBook so strongly to other formats.
Tools you can use to produce DocBook texts.

Don't worry if DocBook doesn't mean anything to you yet: the required knowledge can be learned in less than an hour, and chances are that you will benefit from this knowledge in other projects too, whenever you have to write technical documentation.

The next part is about the actual docwriting:

Setting up the document itself.
Using DocBook elements.
A word or two on language and writing style.
Copyrights and the Public Documentation License.

Finally, we will show you how to add your finished doc to the Firebird project. Main topics in this section are:

Commiting your finished document to the manual module.
Where to ask for commit rights if you don't have them.
Dos and don'ts once you have received commit rights.