The Type of Documentation Open Source Needs

Datamation content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.

I used to write manuals, so no doubt I consider documentation more important than most users. But whatever the reason, I am increasingly convinced that if desktop Linux applications are ever going to receive the attention they deserve, they need not only to have documentation, but to have the right sort as well.

For a long time, documentation has been an after-thought in open source. The culture of open source began as a programmer’s culture, and for programmers documentation has always been a junior position, usually done at the last moment when experts had no extra time for consultation.

This attitude isn’t helped, either, by the fact that many professional technical writers are insecure. To compensate, they claim that what they bring to a project is writing expertise, and that they don’t need technical expertise. Someone else – probably a programmer – can supply the technical expertise. They can just copy it down.

This attitude is understandably considered an imposition by programmers, who have their own tasks to do. More – programmers consider the attitude irresponsible, since whenever they need technical expertise, they are expected to go out and get it. Add the fact that the manuals produced by such writers are minimally useful, and the low opinion of technical writers is hardly surprising. Only a handful ever do their job by making themselves experts in the software before writing it.

With this background, open source documentation has always had trouble finding people to write it. Even an organized group like ODF Authors, which writes documentation for LibreOffice and OpenOffice, has so few people that it is always a couple of releases behind the software despite. When its leader goes on vacation, productivity falters.

Still, the idea that documentation matters is gradually taken hold. In the last few years, several groups for writing documentation have come with supportive publicity, and, all too often, disappeared in silence. In the last few months, Rikki Endsley at Red Hat’s Opensource.com has made a point of running regular articles about writing documentation. But lack of community support remains a problem – for example, Open FOSS Training, which is attempting to raise money to write manuals, has collected only $500 of the modest $2,500 it is attempting to raise through crowdfunding.

Death Marches and Circularity

However, getting documentation is only part of the battle. What is equally important is the type of documentation. Perhaps because open source projects, like commercial software developers, tend to hold documentation in low esteem, too often any documentation is considered enough. After all, if people need help, there are always user forms and IRC channels.

For example, the paint application Krita, for months displayed links on an opening splash screen to documentation that were either incomplete or referred to the last software version. No doubt the assumption was that some documentation was better than none.

If so, that assumption is questionable. The old Krita manual was an example of the kind of documentation that I refer to as a death march through the menu. A death march painstakingly includes items for every item in every dialog window, giving a superficial appearance of thoroughness, but has no place for the connections between features – which is what users actually need.

Often, death marches reduce their effectiveness even more by the circularity of their description. Such circular explanations remain common in the LibreOffice online help, although to be fair, attempts are being made to improve it.

The LibreOffice online help, although it is being improved, has example of both death marches and circularity. For example, on the page for the Position tab in the dialog for customizing lists in Writer, the “Level” field is explained with “Select the level(s) that you want to modify.” The writer knew that the field had to be documented, but, instead of providing usable information, wrote an obvious statement before grimly marching on to the next item.

Similarly, the same page’s entry for the Preview Field is “Displays a preview of the current selection” — a circular statement only partially hidden by the rewording.

To me, this kind of documentation marks where the writer reached the limits of their lack of technical expertise. More to the point, though, it shows a blinding grasp of the obvious that only frustrates users needing help.

Context and Task-Based Documentation

By contrast, in recent months Krita has started adding a more detailed manual. It has its share of death marches and circular explanations, but other parts of it give the background that readers are most likely to be looking for.

For example, the Krita manual begins its discussion of color management with a brief definition, then proceeds through “What is the problem?” and “What is Color Management?” before detailing the components for working with color management, and giving examples for them. A reader using this help should not only be able to solve their immediate need for information, but also should gain a wider sense of the task they are doing. It’s the kind of documentation that can only be written with an understanding of the subject, and next to impossible to fake without the attempt being immediately obvious.

Better still are the LibreOffice manuals, produced by ODF Authors under the supervision of Jean Hollis Weber, an experienced technical writer and documentation manager [disclaimer: I am currently producing a book with Weber as editor]. Open one of these manuals, which are free for the download, and you see a telltale series of participles in the table of contents.

For example, looking at random in the Getting Started manual, I find, “Creating a template,” “Creating a template from a document,” and “Creating a template using a wizard.” These entries indicate not only a task-based approach, but a hierarchial approach, in which the last two titles are a sub-set of the first, making them easy to find. Even more so than documentation with context, such task-based instructions are possible only when someone has worked extensively with the software and had time to understand it.

Tech-Writing and Project Pride

“Technical writing” is a compound term for a reason. It requires both knowledge and communication skills, which is another reason why it is rarely done well.

However, despite the difficulties, open source needs to focus on improving documentation just as, around 2007, it started focusing on improving graphical interfaces. To deliver applications without the best possible documentation is a form of rudeness – a signal that the developers don’t care about user.

Even worse, without sufficient explanation, developers are coding into a vacuum, making their efforts less accessible and risking a hostile reception of their work. Contrary to the common perception, ensuring effective documentation is not slumming – it is showing professional and a true pride in your work.

Photo courtesy of Shutterstock.