Over the last little while, I’ve been slowly (very slowly) chipping away at a fair-sized personal writing project. I have a number of applications — both commercial and Open Source — at my disposal, but I chose to work on the project using LaTeX.

LaTeX (pronounced lay-tek) is a document markup and preparation system that has a long history in academia and scientific research. But it has a number of other uses, too. Including my project.

While I’ve been using LaTeX on and off for quite a few years, it’s been a while since I’ve been immersed in it. To put it bluntly, my LaTeX kung fu is lacking at the moment. But I am getting reacquainted with it. I’m also remembering why I like using LaTeX and am being reminded of some truism about documentation as well.

Why LaTeX?

First off, it’s a text-based format. I can write documents on any computer that has a text editor. The editors that I use on my laptop and netbook have LaTeX extensions which make adding markup to my documents easier.

LaTeX is designed so that you focus on content rather than formatting. You type, add markup, and when you generate a PDF of your document, LaTeX does all the formatting for you. Admittedly, the basic document types — like letter, article, report, and book — are kind of bland. They’re very nicely typeset but they’re plain. You can easily change the look of document using classes. Classes are like templates, and there are a large number of them.

What about structure?

For my project, I’m using the book document type with a few extra classes added to change the fonts, the page size and layout, and to add funky chapter numbers. But I’m adhering to the LaTeX structure for a book.

LaTeX divides a book into the following segments:

• Part
• Chapter
• Section
• Subsection
• Subsubsection
• Paragraph
• Subparagraph

I’m not using subparagraph; never have. It’s a bit too granular for my needs. Following that structure gives me a book that’s not just well-formatted, but one that’s logically broken down. There is, or at least can be, a logical and well-defined flow to the text. Of course, a lot of that depends on how the content is written.

I can, of course, not use the markup to denote the portions of a book that are listed above. That would mean doing what many people who use word processors do: ignore styles and manually apply formatting to everything. I’ve seen that done with documents written with LaTeX and the results aren’t pretty. Section and chapter headings don’t quite look right, and the table of contents (which the LaTeX processor automatically generates) is empty.

Applying this to documentation

A number of people use LaTeX to prepare documentation. But that’s not the application that I was thinking of. Instead, using LaTeX forces me to consider the structure of what I’m writing, and how all the little bits and piece of a project fit together. Structure is one of the foundations of good documentation, and a document that’s been poorly planned reads as if it’s been poorly planned. You really need to have that structure defined, and understand how:

• Your content fits into that structure
• To work within that structure, and work around it when the need arises

On top of that, LaTeX allows me to focus on the content. The more I do that, the better it is. Well, at least that’s my hope. I prefer to let the tool do all the fancy work. All it takes from me is a some effort up front to specify which classes I want to use.

Sounds a lot like using XML for documentation, doesn’t it?

Thought? As always, feel free to leave a comment.

Related posts:

1. A few thoughts on writing with a wiki
2. Can lightweight markup languages be used for documentation?
3. Structured authoring for everyone