Who Should Write the Docs?

User Documentation: It's tempting to hire an unemployed English major so that the writing is good. But the point of documentation is not good writing, it's useful writing. So skip on the writing expert and pick a system user. Someone who actually knows the pitfalls of the software in a real work environment will create a much more interesting and useful product. (Maybe hire the English major as an editor)

In Line Code Comments: I'm amazed at how many developers don't comment their code. I'm not talking about /* Start of loop */ -- oh duh. I could see that in the code. That kind of comment is stupid. What I am talking about is /* this logic is more complex, but it handles leap year where other alternatives don't */. In 5 years what would I need to know about this code? Document that. We need to demand of ourselves and our peers that undocumented code is unfinished code.

Compilation/Configuration Comments: For small shops with limited resources this is critical. Either the developer or whoever is in charge of deployment has to document this stuff. It's not fun. It simply must be a discipline.

Design Documents and Other Construction Artifacts: Nobody. No, I don't really mean that. But, as a general rule it seems that too high of a percentage of documentation time is spent generating documents that are useful for only a brief period during the early construction phases. These "big picture" documents are important. But there also needs to be detailed technical documentation describing the finished system. That step is so often left out.

Wiki, wiki, wiki: A document is never finished. Make it easy to update.

Congressional Website Overloaded

I just wrote my Congressman and www.house.gov was reacting VERY slowly. Must be a ton of people sounding off about health care. I wonder what the numbers look like. Must be huge. Probably a big ugly security layer eating up 3/4 of the CPUs.

Why We Don't Document our Software

It starts with a phone call, frantic email, instant message, or personal visit. System X is down. The programmer for system X left the company 5 years ago and nobody has touched it since. If it doesn't get fixed soon the widgets will start sprouting legs and marching on IT. They'll be torching the place shortly if you can't fix it fast!

Quick, where's the docs? Um. . .

"this space left intentionally blank"

Yeah, it really stinks. If it hasn't happend to you yet, just wait, it will. It's ironic since as a software developer I'm proud to work in a very rational field. Software Engineering is one of (if not the) most logical profession in the world. You would think we wouldn't allow this kind of chaos to happen. But we do. All the time.

Because we are so logical the fact that we rarely document our work therefore can not be perceived as illogical. As noted in a previous post common excuses such as: poor writing skills, too busy, etc, don't stand up under scrutiny. There must be a rational, logical explaination.

In economics they teach a principle called "opportunity cost". Whenever a choice is made there are always other options that are excluded. For example, during the years I studied software engineering I simultaneously lost opportunities to study other subjects. More pertinently, the hours spent writing documentation are not spent writing code.

Software Engineers are hired to write code. The flashier, cooler and showier the better. Writing documents may earn a polite "atta boy" from the boss (followed by "how's project X coming along"). The only way to earn real kudos is to deploy code or rescue the company from a dire emergency. (The irony is that many of these dire emergencies are created by undocumenttion.) From time to time we may out of guilt write some docs, but inevidably we gravitate towards the rewards, leaving behind a wake of sparsely documented systems. What is unusual is not the lack of documentation, but the documentation that does exist.

The solution is breathtakingly simple: treat documentation as the equal of coding. The open source community has already illustrated that this can be done. Since I haven't been a part of an open source team I can't verify this personally, but from an external view I see some factors at work that I don't see in software for hire.

1. the documentation develops in parallel with the code
2. documentaiton authors are rewarded equally with code authors (in non-material ways)
3. the documentation is highly visible to the people handing out the rewards

If we can find ways to implement these concepts inside software for hire shops my bet is that poor documentation will become a thing of the past.

P.s. Anyone out there already doing good documentation I'd like to hear some suggestions. Pleas post a comment.

Response to The World’s Economic Problems are Like 2 Cross-Wired Thermostats

Recently one of my favorite bloggers Harwell Thrasher posted an interesting (and well written) article on economics. Unfortunately, many of the basic assumptions underlying the article are deeply flawed. Since these assumptions are generally believed by the majority of educated Americans I decided to dubunk them here in my blog. For many years I believe these myths too, so by no means am I degrading the great work Harwell does in his blog.

First, there is an implicit assumption that money is a constant scale–-similar to a temperature scale. The exact opposite is true. Money is a commodity with a value that varies greatly over time and place. There are countless examples—a lunch that costs $1 in El Salvador may cost $5 in Tennessee and $10 in New York City. More pertinant to the economic discussion a dollar spent on housing in some markets will buy twice as much house as it did a couple years ago. In general, during recessions the value of money increases dramatically. That increase in value is what triggers entrepenurial activity and re-ignites consumer spending. (i.e. "Wow, this is cheap--I'll buy it." As more sellers and buyers move into the markets the economy recovers.)

The increase in the value of money has a secondary effect of triggering a round of bankrupcies. (It's harder to pay off debts with increasingly valuable money.) Popular opinion labels bankrupcy as a bad thing. It is to the person going bankrupt. But for society at large bankrupcy is generally a possitive. It removes assets from (mis)management that ran it into debt (generally an indicator of future losses) and transfers those assets into the hands of managers who have money to invest (generally an indicator of future success). This reshuffling of wealth into the most capable hands helps lay the groundwork for recovery.

Second, there is an assumption that recessions/depressions do not end without government intervention. Historically the opposite is true. Recessions/depressions are self correcting. (Of which there are numberous examples--three in my lifetime alone and I'm not that old) The only time a recession won't self correct is when government intervenes. Most notoriously Japan’s Lost Decades and our Great Depression. Unfortunately, the Great Depression is so deeply impressed in our collective oral history as a unique event that we don't realize it was simply an ordinary recession that wasn't allowed to self correct.

Third, there is an assumption that recessions are financial events. The cause is actually a misallocation of labor. This misallocation is typically created by a credit bubble that draws resources away from productive activities into pseudo-productive activities. (Usually good activities, but WAY too much of them.) The solution is to reallocate the unnecessary bankers, construction workers and auto workers into productive activity.

The only government solution that might work is education/retraining. The other common government solutions all work directly against the steps needed to recover. Bailouts attempt to keep misallocated workers misallocated. Temporary diversions like building bridges to nowhere and crushing cars are only marginally better since they divert labor into temporary (and wasteful) activities rather than into permanent productive employment. Quantitative easing (printing money) is probably the worst government solution of all. As noted above a deflationary phase is critical to generating a recovery. To the extent that the Fed/Treasury succeed in preventing deflation they prevent recovery. Other financial controls like minimum price and wage controls have the same dampening effect since they prevent entrepreneurial activity from taking root.

From a political perspective the efforts of the Bush and Obama administrations (the short-term economic policies have been similar in both administrations) have been brilliant. However, the economic effect of these policies (if continued) will result in years of prolonged recession. (1)

It’s frustrating to see this happening and know that the 99.9% of American’s are simply not economically educated enough to understand the mechanisms of what is taking place. My only hope is that we will become frustrated enough that we’ll kick out the current leadership team in Washington (Democrats and Republicans) and bring in a new crowd.

1) I have to give credit to Michael Shedlock for introducing me to the concept of an "L" shaped recession--a crash followed by a generally weak economy that doesn't recover. His blog is well worth following.

Why Don't We Document Our Software? Part 1: False Excuses

Quick what's the right answer:

a) We're bad writers

b) We don't like to write

c) We are too busy

d) All o the above

OK, trick question. The answer is: e) none of the above. Here is why:

a) Most software developers have at least a bachelor's degree from a liberal arts school. As a general rule we have at least as much training as the biology major writing the user documentation. Often we have more. Software developers write blizzards of email and fill up message boards with numerous comments. We can write.

b) If this were true why are so many open source projects some of the best documented systems out there? When programmers develop "for fun" we write documentation.

c) There is a kernel of truth in this. Everyone is busy. But the truth is we find time to do what's important to us (and our managers). Documentation just isn't.

In my next post I'll examine the real reasons we don't document our software systems.