Streamline your documentation efforts with the help of these five apps

If you fail to document your systems or projects, you (or those who inherit your work) are likely to regret it. Luckily, plenty of apps are available to simplify the task.

If you're a system or network administrator or a programmer, you know one of the most tedious exercises you can undertake is documenting your systems, networks, or projects. Thing is, without proper documentation, you may as well build it all and forget how you did it -- because that information will slip from your memory. Or worse, you'll be relieved of your duties and those who step in to fill your shoes will be clueless as to what you did. Either situation will reflect badly on you. To avoid that, you must do your documentation.

But what's the best way to approach it? Do you just open up a word processor and start typing random bits of information? Or do you use an application designed to simplify the process? It makes sense to take advantage of a specialized app, but which one should you use? I have come up with a list of five useful apps that can simplify your documentation chores. They're either specific to a task or general enough to aid in most situations.

Note: This article is also available as a photo gallery.

1: Sphinx

Sphinx (Figure A) is a text-based tool that's geared toward those who have a solid understanding of how program documentation works. It's available for Linux, Mac, and Windows and includes features to help you get started as well as to build your documentation. Your first step will be to run the sphinx-quickstart, which will build the directory structure for your documentation. It will ask you numerous questions (in most cases, the default answers will work) and then instruct you to populate your master file and create other documentation source files. After that, you run the make builder command to build the documents.

Figure A

2: Scribus

Scribus (Figure B) isn't designed specifically for creating documentation, but it's a powerful page layout system that can produce effective results. Instead of fighting a word processor (one that will have you tearing out your hair because it refuses to handle word wrap or allow proper image placement), you want to use a tool like Scribus. With Scribus you can control exactly what goes where -- text boxes, images, layers... you name it. Scribus is available for Linux, Mac, and Windows and can generate professional-looking, four-color, printer-ready PDF documents you can distribute to staff and clients.

Figure B

3: Dia

Dia (Figure C) is a free open source diagram editor that enables you to create simple system diagrams without the headache of learning to use one of the more complicated diagramming tools. Dia offers a large selection of objects for your diagrams, ranging from standard network objects to flowchart shapes to cybernetics. The interface is completely drag and drop, so you should be able to get diagrams started and finished quickly. Once you've completed your diagram, you can save it in the Dia native format or export it as an image file (which you can then import into the likes of Scribus).

Figure C

4: Geany

Geany (Figure D) is not just a simple cross-platform text editor. It's an easy-to-use graphical text editor that can handle your documentation tasks in XML format (think DocBook). Geany features syntax highlighting, code folding, symbol name auto-completion, auto-closing of XML and HTML tags, and call tips, among other things. It also supports a large list of file types.

Figure D

You can create projects within Geany and specify things like filetypes, encoding, and line endings on a per-project basis. Although Geany is geared more toward coding projects, it's an outstanding tool to help you construct your documentation. There is also a plug-in called GeanyGenDoc that will automatically generate documentation based on source code. To learn more about GeanyGenDoc, take a look at the online manual.

5: Calibre

Calibre (Figure E) is ready to take your documentation and convert it to an ereader format. Documentation can often get incredibly lengthy, and you don't want to have to carry it around wherever you go. Why not generate a .MOBI or .EPUB file from your original .HTML or .DOC documentation so you can have that information on an ereader, tablet, or smartphone? With Calibre you can also generate a handy table of contents for easier documentation navigation.

Figure E

Worth the effort

Documentation doesn't have to be a nightmare. With the right tools you can get your documentation caught up so that when others have to take over, they have all the information they need to get the job done with efficiency and accuracy. Without documentation, any task is going to wind up costing more time and money