The Uselessness of Documentation
I’ve long been a fan of documentation, it was one of my favorite roles at Data Doctors, and no matter what employment I find, it seems I’m always documenting some procedure or standard. Documentation allows me to exercise both my interest in writing, and my OCD tendencies at the same time.
However, I came to a startling revelation today, and that is that documentation is, 90% of the time, worthless.
Now I work in an industry that relies on documentation. Without datasheets from semiconductor manufacturers, I would be out of a job, and an industry. So when I speak of documentation here, I’m referring to “explaining to people what they should do,” or, procedural and standards documentation.
It started today at work. A number of us in the lab are working on design/layout projects simultaneously for the next revision of the WiSARD. Part of this is generating schematics that not only are correct, but are readable when printed, and have some sort of versioning or tracking information printed on them. In my world, this is usually done with a sheet template (see below).
Circuit Schematic Title Block
Now, I was the first to reach this stage in my project (I had the easier project) and when I needed to know what the lab’s standards were for this, I simply looked up previous schematics, and made mine match as closely as possible using the tools available. There might have been some document in the repository that explained exactly how I was supposed to accomplish this task, but I didn’t even look. I simply figured it out.
I ignored the documentation because I’m intelligent enough not to need it.
A few minutes later, Dan needed to do the same thing, and Kenji asked me to show him what I did. I spent the next 5 minutes looking over his shoulder, explaining step-by-step which options to check and buttons to press. On the way back to my desk, I realized that I could have simply handed him my schematic, and had him match it. It would have saved me about 4.5 minutes, and he would have easily figured it out.
Dan could have ignored the documentation because he’s intelligent enough, but I forced him to use it, and it wasted us both time.
Later that evening, I was having lunch with a friend who is involved in my school’s switch between webmail providers. One of the issues they’re facing is how to educate students so that they can transfer their address book between products. After only a few minutes of conversation, we declared that it didn’t matter, because the intelligent users are going to take the 15 seconds to Google the answer, and the unintelligent ones aren’t even going to try, they’ll just call support.
The users who need the documentation, and can’t figure it out on their own, aren’t going to look for it. Any way you cut it, creating documentation is just a waste of time.
Now, this isn’t a 100% rule, there are times, like component documentation, where you won’t be able to sell your product without it. Other times, like in a reasearch or grant project, you will be required to document things. But in the cases where you have a choice, it’s pretty much nailing Jello to the wall.
June 3rd, 2009 at 3:01 pm
I’m a big fan of the 80/20 Rule, but in this case I don’t think that just because 90% of documentation is useless to you means that documentation should be discounted entirely.
I think you applied-type Engineers really are too focused on suffering through a more difficult method of solving your problem simply because hard work builds character. Sure, I’m an intelligent problem solver: I can read through someone’s spaghetti code (most likely not CS educated) and determine exactly what each statement is doing… but why would I want to suffer when it’s unnecessary? Abstraction, my friend, is the key to elegance.
Documentation is laughably simple to write nowadays, especially for source code. You can generate your documentation (even with an extraordinarily complex Object-Oriented taxonomy) straight from the comments and even in some cases your function/variable names/types.
You remind me of this guy.
June 3rd, 2009 at 3:05 pm
BTW, Welcome to the blogosphere!
You know, you needn’t bother with any other category besides “Rants”
June 3rd, 2009 at 7:31 pm
I’m pretty sure the tag ‘rant’ and the two qualifications in the post mean that I don’t think documentation “should be discounted entirely.” Second, code documentation (within reason) falls almost completely under the category of “component documentation” a facet I specifically allowed was necessary.
That out of the way: abstraction is most certainly NOT the key to elegance.
Sometimes, abstraction is a part of an elegant solution. Abstraction, by its very definition requires that you ignore something. In a very few cases this is perfectly safe, however, in most cases each of these things that you ignore will impact your final product in some measurable way.
My favorite example is file systems. Linux likes to say that “everything is a file” and Windows says “everything is local.” Although both these philosophies can allow a wonderful set of features to the product: *nix’s hardware-independent file tree, and Windows’ ability for a dumb app to use complex distributed data stores, they also introduce ‘glitches.’ As a developer, you must completely understand the effects of these abstractions, only then are you able to even attempt to work around them, and build a leak-proof abstraction.
I’ve found that most of the frustrations people have with technology are effects of abstractions. I love my iPod, it keeps me sane, and as much as I believe that Steve Jobs is quite possibly Beelzebub’s son, it has a wonderful design, and decent interface. However, that interface is abstracted. It’s really one big button that someone decided should do about 30 different things, depending on its state. Herein lies my frustration. I am unable to wake my iPod out of its sleep/screen saver mode without changing something else. Some developer at Apple, while abstracting away it’s interface, forgot to treat the sleep state as a programmatically discrete state. Instead, sleep is either the play or pause state, meaning that the buttons do what they would do in those two states. What they should do, is wake the device up. So to see the currently playing track, if my iPod is asleep, I have to change the volume, pause, skip tracks, or move to the ratings screen.
Some things are hard and ugly because there is no way to do them otherwise, and that makes us want to abstract them so they’re pretty. Most of the time this works, but when you abstract, you have to make sure you put limits on the abstraction’s use, or you’re going to hit a leak, and that’s when you’re “infinite space, infinite time” model causes a virtual memory error.