In my day job I am a Project Manager, and one of the things I constantly try to get is good documentation. I hope I have even produced a little of it myself. But there is no topic on which I get more resistance than on creating good documentation. No one ever has time to create it, but somehow they find the resources to pay the price when they don’t have it. If getting good documentation is hard in the corporate world, how about in the Free Software world? It is equally difficult. I can’t tell you how many times I have tried to access the Help system for one of my KDE applications only to get an error that says there is no Help material available. You really feel sometimes like you are being told “We wrote it, now you figure out what to do with it.” And part of the reason is that we don’t always think about it properly (in my opinion).
I would start by distinguishing between two kinds of documentation: technical, and end-user. Technical documentation, as the name implies, is the sort of thing that the developers could provide if they chose to do so. This could get to the very deepest level of code documentation, but even if it lives at a somewhat higher level, it is not end-user documentation. And the question of whether it even exists remains. Developers like developing, but they generally don’t like documenting. And in Free Software many of these people are volunteers.
But the topic of end-user documentation takes us in a different direction, and one where people with the right skills can be very helpful. It can also be little frustrating. I recall one experience I had where I offered to help create end-user documentation for an application. When I asked to see what they had, the response was “We don’t have anything, that is what we want you to do.” Now i like to think I am a good writer, and I know I have been praised at work for the documentation I have written, but any writer needs something to start with. At work, I can make the technical people sit down with me, answer my questions, and so on. And you really need something like that to do good documentation. Good technical documentation can get you started, but to do good end-user documentation you will need to have some kind of access to the developers. And if the folks on the project you want to help don’t understand this, you need to explain it to them. They may want someone to come along and just magically make something happen without anyone else on the project being involved, but that is just not feasible. Good documentation is a group effort, really.
In writing for the end-user, you need to be able to think a little differently. End-users are, by-and-large, not technical. There can be exceptions to this rule, but this is a good starting place for writing the most useful documentation. And the best way to do this by thinking of “stories”. The Agile community tends to do a good job of this in terms of software development, but you need to carry this into documentation as well. You could write a book on this topic, and I don’t have that kind of space here so I will be somewhat more brief. Stories in this context means picturing a typical user of some kind, and imagining how they might try to use the software. Who is this person? Be specific – give this person a name, an age, a sex, a background. The better you do this the better able you will be to get into this person’s skin and see things the way they do. Then look at some questions they might have.
- Why would I want to use this software?
- What do I hope to accomplish here?
- Would I use this infrequently, or daily?
- Would I use this alone, or with other software?
And that is just a few of the questions you might want to ask at the beginning. By answering them, you set a direction for what you want to do. And if you can begin here and you can write out answers that end-users can make sense of, you can make an invaluable contribution to Free Software.
One last note is about translating documentation. Free software is in international in scope, and often the people who need it most also need it in their own language. If you can translate the documentation that is also a much-needed contribution. Many projects are looking for help with this aspect of the documentation. Just offer to help.
Listen to the audio version of this post on Hacker Public Radio!
