The Document is the Program Hairy Larry 01 Jan 2000 23:59 1 Originally published on freshmeat.net http://freshmeat.sourceforge.net/articles/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 (defunct) 
deltaboogie.com