Information sources for documenting free software

Off the Beat: Bruce Byfield's Blog

Nov 23, 2009 GMT
Bruce Byfield

Last week, I wrote about the problems of writing documentation for free software. This week, I'd like to write about the practical challenges -- specifically, what knowledge you need to write free software documentation, and the available sources of information.

To take advantage of the information available, you need a reasonable grasp of the written language. Contrary to the impression that many salaried technical writers give, you do not necessarily need to know how to parse a sentence or be a wizard at the black arts of grammar. Text that requires minimal editing is always an asset, but free software documentation is a communal effort. If you're lucky, another documenter can compensate for your less than perfect syntax.

Nor do you necessarily need a computer science degree. The more knowledge you bring to a documentation project, the better, but so long as you have developed expertise by the time the project is finished, that is what matters. If software developers always waited for someone who was an expert to document, there would be even less documentation than there is now.

At a minimum, you need to become an expert user of whatever you are documenting -- a general rule that is relatively easy if you are documenting a desktop app, but can be challenging if your subject is a sysadmin utility and your knowledge of networks is minimal.

However, you do need to know a couple of basics, so that you can learn. For instance, if you are documenting while the software is being developed, then you probably need to know whatever version control software that the project uses, so you can check out builds.

To use those builds, you also need to know how to compile the code, whether it's a case of memorizing the old configure, make, make install formula or something else. Except at milestones such as alphas and betas, typically, you won't find packages conveniently ready for use, so you have to compile for yourself.

The knowledge of a documentation format can also be an asset, but typically it is less important. LaTeX, XML or HTML can be picked up on the fly, but without an understanding of version control and compiling, chances are that you are isolated from major sources of information.

Exploration, empathy, and working relationships

One of the first places to research a documentation project is lists of specifications and features and comments in the source code. These documents tell you how the software is supposed to work -- although you can never forget that how it actually works may be quite different. Sometimes, features are not implemented yet. At other times, depending on how the project is organized and how its developers work, features may have been added after the initial planning and without being mentioned in the comments. But any planning documents, however complete, can give you a preliminary sense of the size of the project and how the documentation might be organized.

If any previous documentation exists, you can compare it to the planning documents for the release in development. By doing so, you can see what old material can be kept, where additions can be made, and what may be inaccurate in the old documentation.

Once you compile the software, you have another information source. Go through the software menu by menu if it is a desktop app, or option by option if it is a command line tool. But don't stop there -- a list of functions is one of the least useful forms of documentation, especially if the documentation is for new users. Instead, start trying to build use-cases and work flows so that you can use them to organize the documentation.

Don't forget, too, to share your experience of the software with the developers, including places where you have trouble understanding what to do. One of the best ways to convince developers that technical writers are useful is to share your findings with them, in effect offering the first user impressions they receive.

As you explore the software, keeping asking yourself what problems a typical user might have with the functionality or interface. Imaginatively projecting yourself into the user's position is difficult, especially late in the project when you have come to know every line of code as though you wrote it, but the effort can become a source of information in its own right. In addition, the effort can compensate to some extent for a lack of user testing.

Still another source of information is the developers themselves. In commercial development, I have often seen documentation and development proceed with next to no interaction between them. But in free software, there is no excuse for this lack of cooperation. Frequent the developers' mailing lists and IRC channels, and make yourself known. Cultivate working relationships. Be respectful and show that your feedback as one of the first users can help to improve the software.

Keeping in touch with the developers is often essential for documenting and keeping aware of changes. Just as importantly, it means that you are more likely to have access to yet another source of information -- the peer review. If you are working with other technical writers, you can review each other's work to a certain extent, but for a review of the technical aspects of your work, no one is better than a developer who has written the code you are documenting. More than anyone else, they can tell you where you are inaccurate or wrong, or what is missing from your documentation.

The advantages of free software for writers

In many ways, writing documentation for free software is not much different from writing for commercial development. However, free software documenters have several advantages that their commercial counterparts rarely share.

For one thing, while there are never enough free software documenters, they are far more likely to work as a group. That means that you can often consult another writer for information, especially when you are bringing yourself up to speed. By contrast, commercial technical writers frequently work solo unless they are at a larger company.

For another, while free software developers, like their commercial counterparts, often hold the prejudices against technical writers that I mentioned last week, in my experience they hold them less strongly -- especially if you show yourself willing to learn and to take the initiative to educate yourself. The reason, I suspect, is that the essence of hacking is self-directed learning. What you are doing as a documenter gathering information is something that many free software developers have done for themselves and can readily understand.

But perhaps the most important difference is that, in free software, the information sources that documenters need are readily available. No one is likely to refuse you access to the code, and, if one developer proves unhelpful, you may be able to find another who will work with you. So long as you know how to check out files from a repository and build them, you need very little to document free software other than a willingness to explore and work with developers. The rest is largely a matter of the effort you put in.


comments powered by Disqus

Issue 195/2017

Buy this issue as a PDF

Digital Issue: Price $9.99
(incl. VAT)