Are we documenting the wrong things?

James McGovern blogged recently about his dislike of documentation as part of software development.  While I disagree with his style and penchant for hyperbole, McGovern asks some good questions.  Do we create documentation “because we should” or do we create documentation in situations where it has proven useful, where people read the documentation, and where actions are taken based on that documentation?

McGovern concludes his post with the following question:

“I am of the belief that documentation should explain decisions taken and not taken, Why an approach, architecture or algorithm was selected and what else was considered and rejected. Bet the developer in most shops wouldn't have documented this since he/she may not even have visibility into the choices made along the way. So, when you are asking for documentation, what are you really asking for[?]”

I agree with both his statement of value (Documentation should explain decisions) and his concern about having developers do the work (he/she may not even have visibility).

But let’s take that one step further.  If documentation is valuable in that situation, and if developers can’t meet that need… then who can?

In my experience, the architect is one key person who has visibility to the choices made along the way.  She may be a system architect (for technical decisions), a business architect (for localized business decisions), or an enterprise architect (for cross-organizational business and technical decisions).  When properly supported, an architect is one of the few people charged with documenting alternative designs, getting discussion and consensus, and building a solution that everyone can buy in to. 

But what would that documentation look like? 

This architectural document is NOT a design spec.  It is NOT a requirements document.  It is NOT an API. 

Useful documentation from an architect needs to focus on decisions.  From those decisions, come rules. 

In my current practice, I have developed a new document type called a Technical Policy and Advice Document or TPAD.  This document is focused on a single key technical decision (with all motivations, scope, exceptions, and signatories).  These are “technical policies” in the sense that they are decisions made and ratified across a group of people.  The second half of the document is “advice” which describes a design useful for implementing the technical policy.  The design is documented using architectural models and the allocation of responsibilities.  The document is short (less than 10 pages) and specific.  The document includes both a business decision and a technical approach for executing it. 

I’ve had a lot of “push back” against bringing together these two elements in a single document.   There is a downside in that signatories can’t agree to “part” of the document.  Different people have to agree to both parts.  Putting them together in a single document make for a more difficult decision-making process.   On the other hand, Microsoft is a company where the opinion of a technologist is taken very seriously.  Business decisions are influenced by technologists, and if you go to one and not the other, decisions are simply not made.

For documentation to be useful, it has to be used.  This documentation is useful because projects can be based on it, and technologists throughout the company can see the high-level business people who have made a decision.  If they don’t like the decision, they can speak to those business leaders.  This visibility helps prevent passive-aggressive business behavior. 

Project managers and Developers can read that documentation and take actions based on it.  It is architectural at the business level as well as the technical level.  And, hopefully, McGovern will like this aspect: developers don’t write it.