I had a few conversations today involving documentation in email and otherwise. One was griping about someone else not writing documentation. I had someone saying developers don’t like to document, which is a fair statement, but it’s like saying that they don’t like holding heavy bricks over their naked feet. That’s the equivalent, and if you’ve been around a while, you know that. Even the best coders with perfect memory don’t like explaining their code to others over and over, and it’s a blessing for them in that way. 

Later that day, that person griped about someone writing documentation because they needed something done fast.

Another person and I were going back and forth by email about documentation (oddly related to the same thing), and the perspective presented was that automated documentation was the way to go. I’ve seen automated documentation. Developers work around it. “Oh, I have to put something above the header for my class. I’ll write something witty”, instead of accurate, or both, and 3 years later you get hired in to stare at functions named after this person’s cat, or SuperDuperIntegrator, or – my personal favorites – the Monty Python characters (seen it). That’s just one of the many problems.

The idea behind documentation is that things should be easy to find, easy to read and comprehend if your IQ is above 90 and below 300. It should be accurate, clear and concise – or as close as you can come to it.

Over the years, people taking large amounts of your time to explain the same documentation over and over again causes you to write better documentation. You may not be the best at writing it, but when you’re pestered by people over the years, you end up spending more time about the questions that will be asked and answering them in advance. I’m not kidding. What’s more, it actually helps you with your coding because of it because you’re thinking as you do it, “How do I explain this?” It’s a code review in your head by people’s past implicit criticisms of your documentation by making you repeat yourself.

Documentation becomes a habit.

Or you can keep griping about the lack of documentation by not writing any. See where that gets you. Frustrated teams, tired of having to research everything goddamned thing as if it were the first time, every time. That makes it a bit harder to hire people, because the people who leave aren’t going to be happy. Maybe you’ll be one of those people to go work in a cushy job where there is great documentation (the El Dorado of career software engineers).

Good documentation assists software processes. Requirements traceability alone can become easier. Distinguishing scope at a code level becomes easier. Dependencies are easier to police. Design decisions can be made understandable with things like, “We did it this way because we were rushed for a prototype.” It necessarily slows development because development sometimes needs to be slowed – QA assures quality, software engineers put the quality in and quality, even with a peer review process, is adversely affected by lack of time and in a culture like that the software complexity increases until you’re swimming in a sea of software entropy. Code so fragile that a glance from a user can level it.

Yeah, documentation sucks. I actually hate it though some people seem to think otherwise. Documentation is anticipating needs in the future while describing the present and, if done well, the past as well.

If it was hard for you to figure out, it will be hard for someone else. Document it. If it was easy for you but after a moment’s pause while writing the documentation and looking at the code again, you’ll think about the how, why, what, when, where and who of what you’ve done and may even see things you have missed or see you don’t even understand.

Yeah, documentation sucks. But a lack of it is much, much worse, and bad documentation is almost as bad.