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.

Science and Art in Software Development

Art is best appreciated emotionally. Science logically. The subject matter however can easily overlap. I can stare at the Mona Lisa's enigmatic smile or I can study 16th century clothing styles--all in the same painting.

Software development contains the same split personality. I beleive the best software developers understand when and where to apply both logic and emotionality. It's not unusual for me to be working on a problem and "feel" about it in a certain way long before my logical mind catches up.

Generally, those feelings are right. However--while emotions tend to form more quickly than logic. they also tend to be more extreme. Logic is required for proper balance.

Historically, the general public has seen programmers as all logic and no emotions. I'm not sure that's really true. I think our field is filled with emotional people, they are just emotional about topics that the public doesn't understand. Go .Net, Java Stinks!

(Feel the emotion?)

My Code or Someone Else's Code?

Most software developers if given the choice of maintaining their own code or someone else's code, will choose their own. That's unfortunate. Editing other people's code is one of the best things that can happen to a developer. It's a great way to see what works and what doesn't.

Especially early in a career it's not always obvious what practices are best. Fixing problems in ten year old code is very revealing. My own coding style has become simple, spartan, structured and well documented. I didn't code that way in school or early in my career. I learned it as result of many, many hours of maintenance coding.

Working in someone else's code base is also good for the code. As I noted in my previous post, hacking in new code can be a very destructive process. When editing my own code it's very tempting to hack new features because I know where all the easy attachment points are.

It's not nearly as easy to hack in someone else's code without risking nasty side-effects. That forces a full re-evaluation of the code and often significant restructuring. The result is that the code ends up containing the best of both developers.