Articles / The Document is the Program

The Document is the Program

Over the years, desktop computer users have thrown up a number of straw men to explain why they can't use Free operating systems. The community has shot them down one by one, from "It doesn't support my hardware" to "There's no business software available", but there's still one complaint that too often goes unanswered: "I can't make heads or tails of this manual!" In today's editorial, Hairy Larry discusses the need for documentation and the three types of documents he thinks are essential to any program. Just how important is documentation to the success of your program? Without a doubt, the documents are the most important pieces of your code.

Specifications Documents

Before you write a line of code, you should have at least a preliminary version of your specifications document. This does not mean that you shouldn't write toy programs as feasibility studies. (It's nice to know that something is possible before you commit to a lot of work.) It does mean that before you start on your .001 Alpha version, you should have a pretty good idea of where you are going.

And here's the reason why: Algorithms + Data Structures = Programs. Or, as I have heard it said, the database is the program. I really don't know of any substantial programming project that doesn't rely on data.

Getting your data structure right is hard. Mistakes in your data structure lead to massive rewrites. You have to put a lot of thought into how your database will work and how your code can access it. How can you even think about this until you have a pretty good idea about where you are going?

Of course your specifications document will change. It's a good idea to add version control to your specs from the outset. I'm sure you plan on enhancing your program by adding new features and bringing out new versions. These features will have to be specified, so track the changes in your specs just like you track the changes in your code.

Programmer Documents

I learned that even on projects on which I was the only programmer, I would often come back a month later (or the next day) and wonder "Just what was I doing there?" Now I'm assuming that if you are working on an open source project you are hoping that other programmers might get involved. How can you possibly expect them to figure out "What is he doing there?"

Each piece of source code should be documented at the top. Describe its overall function, what modules call it, and what modules it calls. I find it helpful to write this before I start coding to focus my attention on the problem at hand. In the source, each block of code should be documented with inline comments. What does this variable do? What algorithm am I using here? Why does this piece of code even exist? These questions and more should all be answered by inline comments.

You also need a single large document for the entire project. This document should describe the data structure and the overall structure of the program. Each module and its function should be included. You also need a list of all the documents for the project. Include a way to get in touch with you. Just because you understand what you are trying to say doesn't mean that the programmers reading the document will. Make it easy for them to ask questions and include your clarifications in the document.

By providing good programmer documents, you make it possible (not easy, just possible) for other programmers to come on board and help you with your project.

End User Document

The end user document (AKA the Manual) is the most important single piece of your entire project. It's more important than the data structure. It's more important than the code. It's more important than the documents described above. It is also, unfortunately, the most neglected.

Write your manual in plain, simple English. (French, German, Japanese, etc.) Use no jargon. Assume nothing. Describe the purpose of the program. List the major areas of functionality. Include step-by-step instructions on how to get from point A to point B.

How can you possibly expect the user without a manual to know that he has to click on the frammistran before going to the screen where he enters the stuff describing the fujitron? It may be obvious to you, but it's certainly not obvious to me.

I know most users won't read the manual. Instead of shouting "RTFM, RTFM", include context-sensitive help. Online help is the other side of the end user documents. Let your user hit the F1 key and view the portion of the manual appropriate to the task at hand. This is certainly easier than digging out a book or searching through a text file.

Quality end user documentation requires both a single large manual with all the documentation that a user can read or refer to and context-sensitive help at the touch of the finger when he needs it.

Closing

When a student in the Department of Math and Physics, I remember well the gearheads sneering at the English Majors who were having so much trouble with their required math courses. At the same time, there were no required writing courses for the Computer Science degree beyond Freshman English.

After I graduated, I realized that the most important skill leading to advancement was not the ability to do calculus. It was not being able to churn out tons of hot shot code. It was not the ability to design elegant data schema.

The most important skill is the ability to write well and communicate. It doesn't matter how good you are and how hard you work. If you can't communicate what you are doing and why you are doing it, you will be passed over for advancement. The reason for this is simple. The managers making the promotion decisions are not computer scientists; they are managers. They can't read code. They read English. If you can't write English, you just remain a cog in the machine.

Applying this to the world of open source software, it doesn't matter how good your code is. Most of your users will never read your code. They will read your documents. If your documents are well written, the users will find it easy to run your program. If not (or worse, if there's no documentation at all), potential users will hit a stumbling block and falter. They will then decide that the program is hard to use and look for another one. After all, they haven't made a major financial investment, so it's easy for them to walk away and try something else.


Hairy Larry (hairylarry@deltaboogie.com) was a student of music and mathematics at Arkansas State University where he finally graduated with a B.S. in computer science. He remains active in music through his band, Hairy Larry and The Flying Hingarians, and his radio show, "Something Blue". He is chief gearhead for the web sites TV Soup and Delta Boogie.
tvsoup.com
deltaboogie.com


T-Shirts and Fame!

We're eager to find people interested in writing editorials on software-related topics. We're flexible on length, style, and topic, so long as you know what you're talking about and back up your opinions with facts. Anyone who writes an editorial gets a freshmeat t-shirt from ThinkGeek in addition to 15 minutes of fame. If you think you'd like to try your hand at it, let jeff.covey@freshmeat.net know what you'd like to write about.

Recent comments

22 Jan 2000 06:33 Avatar donh

Documentation
OK, here we go with a fairly typical Newbies point of view. I am not a CS major, but I am a PC technician. I have been using DOS/Win for more years than I care to remember.
About 12 months ago, I started hearing more & more about Open Source software. To cut a long story short, I am now running exclusively on Open Source (FreeBSD) and having a pretty good time of it all up.
But the biggest let-down is with the lack of clear documentation with applications!
As has been said before, man pages have their place, and I browse them assiduously, but they are not the best environment for Mr Average User.
Installations aren't that big a problem (now!), though they were at the beginning. Setting up the programme to actually do what you installed it for seems to be the most neglected area, at least for me. Some of the options available are either just plain cryptic or downright geeky in their approach, "Enable Alpha bump-mapping? Y/N" I have no idea what Alpha bump-mapping is, though it's probably something I wouldn't want my daughter to consider doing!
Some (relatively) brief explanations of what each option allows/disallows would be nice. You don't need to go to the lengths that, say, The GIMP went to (a truly excellent manual), but at least something would be nice.
It is my aim to have some of the professional offices (Medical, Veterinary, Dental) in my area, start using Open Source OS's and software in their daily operations. Unfortunately, the lack of easy to access documentation makes it very hard for us to implement many of the appropriate applications, so Open Source misses out again, in favour of Redmond, who, if nothing else, has plenty of documented ways around the shortcomings of their offerings!
End Rant.

15 Jan 2000 02:18 Avatar gregab

Re: I Utterly Disagree

One simple example of a "human software" error report, followed by a serious question:

This program can't do <whatever>. Contact your system administrator.

What if I AM the system administrator? Don't you human software me, OK?

15 Jan 2000 02:17 Avatar gregab

Re: I Utterly Disagree

One simple example of a "human software" error report, followed by a serious question:

This program can't do . Contact your system administrator.

What if I AM the system administrator? Don't you human software me, OK?

12 Jan 2000 09:04 Avatar AHinMaine

Re: I utterly disagree
Big, huge, gaping holes in your logic there. First, you're forgetting a big one, end users are basically stupid. Anyone who has been in the support side of things knows this. While even in the most poorly written of software, a user should at least be able to figure out how to, say, save a document in a word processor, but what about advanced features? Using the same word processor example, most users will not even know what a mail merge *is*, let alone be able to find it intuitively. Most end users are people who cannot operate computers without constant hand-holding and, for some of them, the only hand-holding available to them is the manual.

As far as comments in code go, you're basically saying that it's poor form to use them in your code. Comments aren't poor form used as a crutch to hold up your code, they're also for people who either don't code or are trying to learn to code who will have trouble following the flow of it without help. One part of the point of open source software is so that we can learn from each other, not prevent people from being able to learn and then indignantly scoff at those less experienced.

05 Jan 2000 01:40 Avatar phirate

I utterly disagree
Totally. Utterly. If the code needs comments to be readable, it has been badly written. If the program needs a manual to be usable, it has been badly implemented.

Software is not like a car, it is not like a building, the very design of the program, and its implementation, should shout out how to use it louder than any manual or specification document.

Do you need a manual to work out how to instruct a human to write something? no, don't be stupid, you just tell them what you want. no matter how complex the problem, you don't need a manual, you start by trying with the biggest words, and drop down to shorter words for those concepts that are not immediately understood. Why everyone continues with this manual bullshit when even Microsoft has cottoned on to human software is beyond me.

To reiterate:
If a user can't use your software effectively without resorting to a manual, your software has a bug.
If a programmer can't read your code and understand what it does without screeds of comments (Some comments, obviously, are appropriate), then your code needs rewriting.

Stop writing dumb software.

Screenshot

Project Spotlight

Kigo Video Converter Ultimate for Mac

A tool for converting and editing videos.

Screenshot

Project Spotlight

Kid3

An efficient tagger for MP3, Ogg/Vorbis, and FLAC files.