Charles Engelke's Blog

I’ve been working with DocBook lately, and it’s turning out to
be a great technology for Appia’s documentation. I’m learning as
I go, and sometimes it seems that every step requires me to back
up and learn two prerequisite steps first. So it’s kind of slow
going. I’ve decided to make mastering the basics of DocBook a
project for the month. I’ll learn how to create and edit the
documents effectively, and how to publish those documents to a
variety of different formats. In the process, I’ll set up a
good workbench for DocBook development on my PC.

When I’m done with the project I’ll probably not use DocBook for
several months, or even years. Writing documentation isn’t
something I do often. Most of what I write are short memos and
reports. Those kinds of documents generally only need to be
rendered in a single form, and usually aren’t subject to ongoing
maintenance, so they aren’t well suited to DocBook. What this all
leads up to is that I’m likely to forget a lot of what I learn
performing this project, and have to repeat it when my next
DocBook-suitable project starts.

I’ve grown used to that pattern: intensively learn how to do some
specific kind of work well, do the work for a while, then move
on to something totally different, coming back to the original
work only after a long hiatus. I’m not the most disciplined
worker in the world, but even I finally got the hint. Now I often
take notes when I do these kinds of projects, and use the notes
when I come back later.

So I’m writing these notes for my own use, but they’ll likely be
useful to others trying to get a handle on DocBook, too. So I’m
going to publish the notes in my blog. I’ll be able to find them
more easily in the future that way, and others can read them, too,
if they’d like. I’m planning to post between one to five such
notes each week, until I feel I’ve figured out and documented all
the important basics of the work.

The structure of these notes will evolve over the project, but I
think they will all have several things in common:

This note just sets the stage for the real work to come. The first
note that actually advances our understanding of DocBook will be
next. We’re going to start with looking at what DocBook is, and
how to create basic DocBook files.