I have a few questions for the room on documentation.

I looked through the slides here from a talk Emmelyn Wang undertook (with a Mr. Christopher Ward) on how documentation certainly provides a return on a company's investment and is moreover crucial to the financial health of an enterprise. I wasn't actually at the talk when it was held in Oregon so of course I'm just getting the gist, but the gist is:

• Documentation that has integrity, accessibility, and searchability is key. It serves as the go-to crutch for many processes and in its absence or weakness such processes will have dysfunction and businesses will suffer for it. Think of a call center's staff and how it does its job. Or, think of the scenes from "Love and Other Drugs" wherein Jake Gyllenhaal, as a Pfizer rep in training, tries to recite his talking points on Zoloft that he has to retain before a match at his fingertips burns him. Where does the information he needs to do his job come from?
• Pilot programs in the name of understanding what a process is and how the parties involved fit into it are a good way to start building that documentation which your gut tells you are lacking.
• Documentation is needed for presales.
• Documentation is needed post sales. It will empower your helpdesk, allowing the helpdesk to be... helpful, and hence increase customer loyalty. The slide deck has metrics on how many customers leave companies due to bad customer service experiences and how more than half of the time they are leaving for a competitor. The average business looses half of its customers every five years, but the average business should also be trying to do something about this problem. Improving customer retention is a good money-making strategy. It can cost up to five times more to gain a new customer than to merely keep one from leaving. Empower your own to stem the bleeding!
• Documentation is needed for contacts. A searchable CRM is a must have.
• At the end of the slide deck there is some data on our modern problem of a talent drought in IT. The good news is that if you were to make a pie chart of all of the tech jobs that American companies can't fill that there is a sizable piece of pie which can be populated by data analysts which does not demand an ability to write code.

I am convinced that Emmelyn is right!

The bad news is that I see a geek culture that struggles with documentation. There is a trend in favor of logging errors and also having good commentary when checking into source control, but there is also a trend towards writing readable code in lieu of having code comments, and, in an Agile process, there isn't going to be the upfront documentation of the Waterfall process. The latter two "negatives" are arguably not negatives at all, but, with regards to Agile, retrospective notes are largely the only documentation. It doesn't make sense to type up copy on what your application does when that wasn't defined upfront and is subject to change as development is underway. You could argue that someone should roll documentation on an application when it is "finished," but this doesn't happen in my experience.

At Veterans Affairs, I was put in charge of retiring a server running MSSQL2000 databases in the name of a bigger push to get away from MSSQL2000. Some databases had not been used in forever and could be dropped. Others had to be migrated to MSSQL2008. Largely, the only way to figure out what was what and what application something corresponded to was to speak to various people in the building I was working in. Little was documented.

I then became part of the problem myself. I rolled a bunch of documentation, but when I realized that my whole job was of documentation and playing with Excel and Outlook all day long, I found another job and got out of there. Again, I see a geek culture that struggles with documentation.

What are some potential solutions? Hire the right ratio of business analysts to developers? What will the analysts do during an Agile process? I'd love to hear any feedback!

Fun Fact: Emmelyn Wang is the only human being ever to work at both Headspring and Dovetail.

Addendum: Since writing this blog posting I thought of the stories that drive an Agile process. I suppose at development's end a holistic view of an application could be put together from the stories themselves as the sum of the stories executed upon would add up to what an application does. I've never yet seen what happens at the "end" of an Agile project.