"Linux Gazette...making Linux just a little more fun!"

Contents

• 1 Introduction
• 2 Why should I write documentation?
• 3 What aspects of my project/program should I document?
• 4 How do I write documentation?
• 5 What formats should I use for my documentation?
  • 5.1 File formats suitable for documentation
  • 5.2 Source code documentation
• 6 Documentation formatting with HTML
• 7 Use LyX
• 8 What about PDF?
• 9 Conclusion

1 Introduction

Giving everything a GUI has become a popular trend in the Linux community. This implies that more and more program authors tend to use a GUI-based configuration dialog.

However, you lose an important thing when GUIs are used for everything: documentation. People who can point-and-click are often the one who think: ```Why should I read the programs documentation? I simply point-and-click--and it works.''

But it would be better to encourage people to read documentation. In fact, the better the documentation, the simpler it is to use a program. Take the Apache web server for example, it comes with heavy documentation. As a result, anybody who can understand a little English is able to use Apache and configure it--without using a point-and-click interface.

This article tries to encourage programmers to document their projects, as well as to provide ideas and tips on doing so.

2 Why should I write documentation?

Lots of reasons! More documentation means easier usage. More documentation means better add-on modules. More documentation means happier users. As soon as a user gets stuck trying to get a program feature to work, he or she starts to read that program's documentation. Imagine, therefore, creating well-structured and well-written documentation that will make it easy for the user to get that feature to work.

3 What aspects of my project/program should I document?

In general the following aspects of a program or project should be documented:

1. Basic usage is mostly covered in a man page.
2. More advanced usage can be achieved by listing ALL configuration options in the documentation and giving examples on how to use them (take the very good Apache documentation for example).
3. Source code, of course, because somebody may want to add features to the program.
4. Examples of usage to supply a working basic configuration file and document it heavily.
5. Installation of the program, because not all programs work with ./configure && make && make install.
6. User interface, especially if it is not a common point-and-click one.

4 How do I write documentation?

Use your favourite text editor, as the formats I propose here can all be written using a text editor.

Style is worth mentioning as well. Write your documentation in an easy-to-read style. Do not try to use poetry.

The preferred language for documentation is plain English, as almost anyone who uses a computer is able to understand it. You can always add documentation in your native language as well. But keep in mind that not everyone speaks German or Russian. At least include English documentation for the most basic parts of your project. Someone who cannot understand the simplest parts of the documentation will not read it, and in many cases he will not use that program.

The rest is up to you. Always keep in mind that writing the documentation is the ugliest part of developing.

5 What formats should I use for my documentation?

5.1 File formats suitable for documentation

Use a standard one, nobody likes proprietary file formats. This effectively kills MS Word, StarOffice or anything like that for documentational purposes.

The most simple format is plain text. It can be read everywhere, and everyone can use his or her favourite pager or editor.

If you want your documentation to be printable, L^ATEX is a good choice. It is relatively easy to use, at least for writing a documentation file. Advantages of using L^ATEX are the system-independent output format and a stylish formatted document. You can even export it to HTML.

The most preferred choice nowadays is HTML. It is hypertext, there are readers for all platforms available, and it can be distributed on the project's homepage for on-line reading.

You can also use an SGML- or XML-based format such as DocBook or LinuxDoc/SGML. These formats provide the most flexibility for converting to many other output formats (including formats which haven't been invented yet), or parsing as structured text (for automated text-processing tools), but require a learning curve similar to L^ATEX.

5.2 Source code documentation

Source code can simply be documented by heavy use of comments and suitable variable names. API descriptions in an external file is important, especially if you're writing a library or something else that can be extended.

6 Documentation formatting with HTML

Always use the most common subset of HTML. Do not use frames or Javascript in documentation. Simply use <H1></H1> to <H6></H6> for sections and <P></P> for paragraphs. Read your favourite HTML-Howto for more detail.

7 Use LyX

This my personal tip for writing program documentation. It features what-you-see-is-what-you-mean input and result formatting in L^ATEX, as well as export to ASCII and HTML. Think of it as some sort of GUI frontend for L^ATEX. Always keep in mind that LyX is not a WYSIWYG text processor.

LyX comes with most Linux distributions, with its own documentation file. Give it a try--it's easy to use and the results are stunning.

The export features of LyX make it well-suited for our purpose. You can create a .dvi file of your documentation that can be printed on almost all Linux boxes configured for printing. So even the distribution of a printable manual is easy.

8 What about PDF?

PDF is an extended version of Postscript. Its main disadvantage for documentation is it requires a graphic display or a printer to be viewed properly.

PDF is also less reliable on Linux. HTML files and man pages "just work". L^ATEX files work if you install the software correctly. But there are incompatibilities between the various PDF-authoring tools and viewers, and you may end up distributing a document that somebody can't open or that has some of the text showing up blank in various viewers.

PDF files are also huge, especially if you include pictures and tables. Displaying PDF files is slow compared to HTML, DVI or plain text. You may use it--but I do not recommend PDF for project documentation.

9 Conclusion

Writing documentation can be fun if you use the right tools. Always remember that the documentation should be written so that anyone can read it.

Now, go do it--good documentation is worth the effort.

Matthias Arndt

Copyright © 2001, Matthias Arndt.
Copying license https://www.linuxgazette.net/copying.html
Published in Issue 71 of Linux Gazette, October 2001