Be clear - document

A number of years ago I had a period of time working at a smaller company where I found myself up against the massed ranks of the "big american consultancy" (BAC) on a number of projects. Now clearly they didn't like me as I was doing some high value delivery work and might have occasionally pointed out some minor flaws in the way that they were working. Now what this did teach me however was the following

1. Don't delete any emails
2. Always send a summary email after a meeting even if it isn't full minutes
3. Document decisions - if someone decides something then send them an email confirming the decision
4. Point out the obvious - if someone changes their mind. Point it out to them. If they are a senior stakeholder then do this one on one. Even if they do change their mind then at least they'll feel that they owe you one. If they are competing against your project then make it visible to everyone.
5. Don't rely on a conference call to get you the status. Build up a social network and trust to the water cooler conversations
6. Go to the raw data. If its about development then do code reviews, if its about data warehousing then go to the data quality and volumes, if its about user interfaces then go to the usability studies.

Now what I'm not advocating is lots of massively verbose documents, in those lie doom as the detail is where the weasel professors can live. The important piece here is making documentation clear and small. One notable experience I had with a BAC was where they refused to do Unicode as it was "too hard" for their mainframes (this is despite pointing out that UTF-8 is basically an extended ASCII set) so we went to the standard ASCII set. Testing began and the data had what looked like typos all over the place. Clearly this was an integration (my) problem. But thanks to the very brief documentation we quickly proved that they were sending an 8 bit character set through when ASCII is 7 bit. Oddly the decision was then to move to UTF-8.

The point on documentation is short, sharp, concise and irrefutable. Its there to make decisions visible and obvious and make non-adherence to those decisions an act of wilful stupidity or disobedience.

As a client said to a BAC on one of my more entertaining projects.

"Are you a complete idiot or an asshole?" (it was an American project)

Documentation isn't there to hide behind (CYA) its there to document facts and Just the Facts.

Technorati Tags: SOA, Service Architecture