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.
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.
In general the following aspects of a program or project should be documented:
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.
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, LATEX is a good choice. It is relatively easy to use, at least for writing a documentation file. Advantages of using LATEX 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 LATEX.
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.
This my personal tip for writing program documentation. It features what-you-see-is-what-you-mean input and result formatting in LATEX, as well as export to ASCII and HTML. Think of it as some sort of GUI frontend for LATEX. 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.
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". LATEX 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.
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.
I'm a Linux enthusiast from northern Germany.
I like plain old fifties rock'n'roll music, writing
stories and publishing in the Linux Gazette, of course.
Currently I'm studying computer science in conjunction with
Copyright © 2001, Matthias Arndt.
Copying license http://www.linuxgazette.net/copying.html
Published in Issue 71 of Linux Gazette, October 2001