Recently I have conducted a research survey (on-line) aimed at understanding documentation in IT. Documentation is certainly not glamorous - but it may be the least expensive way to increase productivity. In many of the situations where I do triage work and develop computing models, the striking thing has been either the absence of a picture of the complete system, or partial “individual” views. In my research interviews most respondents literally rolled their eyes when they were asked how well documentation was done!

So I decided to more formally research how documentation is perceived, executed and the value (or loss of value) from not having it. It’s an on-line survey and a number of organizations and individuals have responded based on an invitation to participate. The only thing known about respondents (apart from their profiles) is what organization they come from so that specific feedback can be provided to clients vs the universe of results. It is still open for participation - and if you would like more information about it please email me at Miles@Faulknerconsulting.com.

The survey has now been completed by 75 IT specialists - operating in both corporate departments (60%) and as consultants/suppliers (40%). Expertise is spread reasonably evenly across most computing platforms and between development and operations.

A finding for comment in this update is the disparity of documentation methods between different IT groups. The question was a simple one- asking if different IT specialists had different ways of documenting systems. The answers were no surprise -
4% Not at all differently
26% Somewhat differently
46% Quite a lot of differences
23.2% Absolutely different

What was much more interesting were the number and content of open ended comments - a sample of which are here - (there were 15 comments or 20% of respondents). The main two observations were a lack of standards and different mindsets or views of the same system -

“different training, background, practices; bound to be different without specific standards and templates”

“Each group views the system from a different perspective. As well, priorities of each group are different. For example, project managers may just want a document to obtain client signoff of a system, where developers may need a document that gives enough details so they can support the system.”

And my favorite:-
“Different mindsets. Architects design and think in block - operators think in actions and application engineers think in data flow within their requirements. Our conceptual understanding is the root of how we intend to share our knowledge.”

You will be interested to note that this research finding lines up with a lot of collaborative research that looks at how different specialists work together. Most research points to a tendency of widely different frames of reference - that can be hardened by organizational, cultural and political elements. For instance Lynda Gratton and Tamarra Ericson (Harvard Business Review 8 Ways to Build Collaborative Teams Nov 2007) have studied teams that deal with complex problems or technologies –

“We found that the greater the proportion of experts a team had, the more likely it was to disintegrate into nonproductive conflict or stalemate…” Consider the following – “Members of complex teams are less likely- absent other influences – to share knowledge freely, to learn from one another, to shift workloads flexibly to break up unexpected bottlenecks, to help one another complete their jobs and meet deadlines, and to share resources – in other words, to collaborate.”

Researchers have actually studied these different perceptions or mindsets and have called them “representational gaps”. Mechanisms to bridge these gaps are typically the use of tangible models or more visual communications. This is a catch 22 in IT because if in fact solid documentation or complete diagrams don’t exist or are not used, the bridging mechanisms are not available. Additionally, unlike a building where a team can physically see what they are discussing, IT is highly intangible by nature. There is often nothing to see.

Understanding is thus shared amongst a mix of different and even potentially opposed mental models, which may be a real problem, especially in a crisis situation. (This isn’t great incidentally on conference calls!)

There will be more to come on the research, including the tools being used, problems with documentation and the cost of lost time.