Code Is Meaningless

Computer languages are great for describing how to do something, but they can't explain why. Why add two to the personCounter? Why is statusField set to the empty string when counterField is null? Questions like these don't get answered by code. Code is very good at answering what and how questions, but why questions are completely impossible for it. So documentation was invented to provide a way to explain why something is the way it is. Unfortunately, few use it this way.

Instead, for programmers we have what's called echo documentation:

/**

* Gets a value.

*

* @return value the value returned

*/

public int getValue() {

   return this.value;

}

Many programmers will document their code by simply repeating what's there. There's no indication of what anything is used for, or why it was designed the way it was. Instead of explaining anything they echo the code. This isn't really documentation.

For users, we have a numbered list of exact instructions, in other words, a program:

1. Click the button labeled “Excute”.
2. In the popup window that appears, select the radio button labeled “Process Records”.
3. Click the OK button.
4. Now select “File/Open...” from the menu.

This style is marginally useful, but it still doesn't do what documentation is supposed to do: answer the questions the interface itself can't answer. It doesn't give the user a chance to do anything more than mindlessly follow directions. This is great for computers but human beings need something different.

Your brain needs information to be balanced between how and why just as your body needs nutritionally balanced food. Eating unhealthy food can leave you with the uncomfortable sensation of being full and hungry at the same time. This same thing happens to your brain when confronted with mounds of data and little explanation. You feel dizzy from the sheer volume of information, but are still confused as to exactly what's going on. And just like junk food that passes through your system without contributing much, most data bereft of reasons for its existence will be quickly forgotten. Documentation that's heavy on information but light on explanation creates more confusion than it prevents.

Why is why necessary? Answering why is so important because it helps human beings store information. To understand something, the human mind needs to create a mental model of it to hang details on. Without the mental model, the mass of details overwhelms the brain's capacity to store them, and the brain forgets most of what was said. People feel lost and confused when this happens, because they have no mental map to orient themselves on. But once they have that mental model to organize things around, human beings can remember an enormous amount of information. Although few people can memorize more than ten phone numbers, most people know more than ten thousand words. Meaning creates the conditions necessary for understanding.

Think of the mental model as a data structure that someone builds in their brain. You don't want to shove information into someone, overflowing their buffer, causing them to forget most of what you tell them. Instead you need to start out telling people how to construct the data structure they need to understand your system. Then you can add details, letting the user know where in their mental model the details fit. This way the human brain can store a lot more information, because it has someplace to put it. When someone has a mental model of something, they say they “understand” it, meaning if you gave them more information they would have somewhere to store it.

To see how different something looks once you have a mental model for it already built, look at the following interface:

Afsefioj:	adiefdif
Jheisp:
Diep:
Bivi:

It's just some fields that seem to have nothing to do with each other. Nothing really suggests what should be entered in them or how they would be used. Now look at the same interface labeled correctly:

Protocol:	httphttps
Server:
Port:
Path:

Now, because you already know what a URL is, the fields make sense. You see how they relate to each other and can think of some possible values. The structure in your brain that stores what a URL is helps you understand this interface. Without that information in your brain, the interface wouldn't help you understand what the program is about.

This is radically different from the way programs work. Computer programs always have the internal data structure already decided on, and coded into the program. Human beings, on the other hand, have no preset structure, so the first thing you must do is give them the structure that the rest of the data will be a part of.

Documentation should be about creating mental models. The docs don't even have to be complete; once a human being has a mental model, they can discover a lot of information on their own without instructions. But without the model a person is lost and can't do much more than mindlessly follow directions.