LaTeX: also useful for writing your documentation

Warning: This blogpost has been posted over two years ago. That is a long time in development-world! The story here may not be relevant, complete or secure. Code might not be complete or obsoleted, and even my current vision might have (completely) changed on the subject. So please do read further, but use it with caution.
Posted on 22 Jan 2012
Tagged with:

Sometimes you hear about programs but you never really know how awesome they are until you actually use them. Unfortunately, at this point in life I wished I’ve discovered LaTeX around 15 years ago, when I first heard of it. That would have made the way I would have written documentation the last years massively different. So hopefully I will get you hooked on LaTeX  with this post.

I started to take a look at LaTeX because of a PHP book I’m currently writing (more news on that very soon!). Before I could start writing, the publisher needed to know how many pages the book would contain. So after I made an initial overview, I started to estimate the number of pages. As you might have guessed, estimations are hard to begin with, especially  because I have no idea how the final markup would look like. Writing a A4 page with text on a 10pt font is take many more words than filling a US Letter with 12pt font.

Now probably the first rule of writing a book is: do not worry about the layout. So obviously - the thing that worried my was - in fact - the layout :). Since I started writing the book in NeoOffice, I tried to mimic the publishers layout as close as possible based on other books to see if my page-estimates were still correct. But trying to create a decent layout in such applications would even make Chuck Norris cry. So that was when I started to look for other ways..

I started to look at LaTeX because I was yahoo’ing on how to write books in a decent markup and LaTeX popped up a lot. My understanding used to be that LaTeX was a kind of language that makes it easy to create all kind of mathematical formulas. Which is correct, since it makes this very very easy, but LaTeX is much more than that. It’s an environment where you can focus on writing instead of struggling with markup, while still being able to have full control over it.

I’ve downloaded the LaTeX package (don’t get fooled, it takes around 1.5 GIGABYTE of software you need to download) and a front end application (Latexian in my case). This just makes your life easier because LaTeX source files (.tex files, the things you type) needs to be compiled and takes a while to get this all right as a beginner. But about one hour later, I was absolutely stunned on how cool my book was already looking!

Also, when you look at many (technical) books, the layout looks remarkably similar to the standard LaTeX layouts :-) I found that this made estimations on page sizes much easier in the end.

Not only is it possible to create really cool looking books and documents out of the box, but you can also split your documents in smaller files which you just include from your main document. Since my book is around 170 pages, I have one main .TEX file in which I set some default parameters (for instance, I don’t want my chapters to have numbers, I use code-snippets that are formatted in a certain way etc). This is called a preamble (maybe comparable to a <HEAD></HEAD> part of a HTML file). Every chapter itself is a subdirectory in which I have every section broken down in separate files (with large sections, I even have another sub-directory with each subsection as a file). My main .TEX file only includes all the chapter files so I can easily change the chapters by moving them up or down. Everything else gets automatically adjusted.

I’ve created a simple LaTeX document to show you how a document would look like:

and off course I’ve compiled the result as an exported PDF file.

As you can see, there is some markup here and there in your sources. To make your life even easier, there are packages you can include in your book which can change literally every aspect of your document. For instance, in my book I’ve included a package to automatically create an index, a package to wrap text around images and a package to create fancy chapter headers. Even though on occasion I found myself stuck, I just added a small TODO comment (you can comment stuff, how cool!) and looked up the answer later. Most of the problems I experienced was just a lack of knowledge and the answer was found quite quickly.

Besides being a cool guy for using LaTeX and automatically create very professional documents, LaTeX has some other advantages:

It makes it possible to version control your documents easily.

Since we are not dealing with binary documents but with just text-files. We can use any version control system to version your documents. My book is actually - together with all examples - hosted on a private repository on GitHub. I can find out where I was a month ago, others can see its progress and even possible to collaborate easily while working on the same book (if needed).

Use the editor you want

I’m currently using Latexian, which is a commercial product (but not expensive), textmate and vim. All of them have LaTeX syntax highlighting and spell-check so again, you only need to deal with the markup.

It’s still possible to see what you are doing real-time (only, it’s not really that important anymore)

Latexian has the possibility to automatically compile your .tex-file and display it. There are others that might have the same functionality and it makes it easy when you really need to focus on layout (I had some tables that needed some TLC).

It’s not only for documents.

Lorna Mitchel uses LaTeX primarily for creating presentations. This is something that LaTeX can do easily as well. For more info, read up on Lorna’s blog.

Conclusion

Even though I’m still learning LaTeX true power and discovering more every day, writing (my) documents will be primarily done in LaTeX. It’s easy, it looks good and it has got loads of advantages over most wysiwyg-editors. And there is absolutely no reason not to do it. Even writing things like functional and technical specification files can easily be done with LaTeX (probably even better, since versioning is a very important aspect for those type of documents).

Give it a try for yourself. You will absolutely love it!