If you’re a computer science student like me, then you probably write a fair amount of code. Depending on your coding style you probably write a fair amount of comments too. But do you write about your software or do you just write your software? Chances are you don’t. College computer science courses aren’t exactly writing courses (no matter how much typing you do). While part of a project may involve documenting the concepts behind your program, or why you made a particular design decision, you hardly ever write something like a manual for your software. However, if you’re planning to write production software at some point, especially if you’re thinking about creating something independently or as part of an open source project, then writing a manual might be more helpful than you think.
Writing a manual is more about than just putting together instructions on how to use your software. It’s important to put yourself in the place of someone who will be using your software (and is probably not a programmer). For you your program logic makes perfect sense (if it doesn’t, why is it even there?) but sometimes what makes sense from a programming point of view isn’t quite so simple from a user point of view. Looking at your program from a user’s point of view let’s you think in terms of what’s really useful and necessary rather than what’s easiest to program. Writing a manual is a good way to put yourself in the user’s seat.
The first things that come to mind whiel writing manual is the user interface. How is easy is it to do simple tasks? Where are the most important parts of your UI located? Is their a general cohesiveness in the way things are put together? Are there some things that you know your program is capable of, but are almost impossible to do due to the UI? Theses are all questions that directly affect how your users’ experience. And so they are top priority. If you find yourself taking up two pages describing something that the user will be doing dozens of time each day, then something needs to be changed.
A critical review of the interface will lead to deeper program logic. Are things which appear close together and related in the UI similarly close together in the program? Are the UI and the program logic equally clear and intuitive? Are you unintentionally exposing internal structure to your user? While writing the manual you should keep an eye out for any bad designs, you should also be thinking about missing or broken features. While that doesn’t mean you should implement everything that comes to your mind, sometimes some features are useless without supporting features. After all, your clients aren’t interested in the features themselves, they want to get their work done. If you find yourself writing about how not to do things or what can’t be done in your manual, rather than how to do them, then your program probably needs more work.
Having a written manual for a small art program, I’ve realized that there’s a fairly direct correlation between ease of use and ease of description. If you can explain a function and how to use it in a few lines, it’s probably mcuh better implemented than a description that takes up half a page. The first version of my program was a fairly tedious text-based program which went out of style around the same time as Apple BASIC stopped shipping. The descriptions for each option and how to get to them were equally complicated. Putting together a simple GUI not only made interaction easier, it also choppped down the interaction part of the manual to a few bullet points.
However, when you’re writing a manual it’s fairly easy to write from a developer’s perspective. After all, you have the guts of your program in your head, and you probably already know half a dozen unobvious little tricks and workarounds. You’ll either forget to put them in the manual or you’ll remember and think that they’ll make as much sense to others as they do to you. Chances are they don’t and you really don’t want to be putting workarounds in your manual if they’re hiding a bug. Fix the bug and then write the rest of the manual.
I’m starting to think that all students should at least once have a project that requires writing a user manual for non-programmers. Years of writing code and tearing through algorithms can make you think very differently from the average office worker using your program. It’s necessary to get in touch with your users and how they’ll be using what you give them. So the next time you write your great new world changing program, take a few hours off and write a manual for it.