Jul 072009

I recently had an MRI on my knee. The report was full of words like joint effusion, medial patellar plica, acute medullary bone contusions, and medial femoral condyle. While my doctor could easily read and interpret the report for me, my attempts to understand the report were doomed. This, in part, underlies the problem with documentation–the difference between context and content. Documentation can provide content, but understanding the context requires domain expertise. Knowledge sharing and documentation are definitely issues when scaling agile.

Documentation isn’t the issue, understanding is. Do the developers understand what the customers want? Do the customers understand what the developers are building? Do testers understand what the developers intended to build? Do software maintainers understand what the developers built? Do the users understand what the system does for them? Understanding takes a combination of content and context, and documentation is a poor conveyor of context.

Understanding comes from a combination of documentation and interaction, or conversation–the conversations among people who have a certain knowledge. In a complex situation, documentation by itself may provide only 15-25% of the understanding required.

The Agile Manifesto “working software” principle has two critical components. First, it says that working software is critical to measuring real success, but it does not say that documentation is unimportant. Second, the word “comprehensive” denotes “heavyweight” rather than lean documentation. Documentation necessary, it’s just not sufficient. Agile developers are not anti-documentation, but they are practical about what documentation can realistically accomplish.


Jim Highsmith

Jim Highsmith was the founding director of Cutter Consortium's Agile Product & Project Management practice.


  3 Responses to “Knowledge Sharing and Documentation”

  1. Hi Jim! I agree that documentation is necessary but not sufficient. One interesting thing I’ve started to understand, though, is that while documentation may be a bad way of transferring understanding, it can be a great way to build understanding of a subject – for the writer.

  2. avatar

    Agreed. I learn a lot writing, as often thinking, “wow, I didn’t know I knew that.”

  3. Jim,

    First, Tobias and you are right. On a smaller, more informal scale, I often take notes during meetings even though there will be minutes, or the presentation being given will be shared with the audience. Well-intentioned people will sometimes pipe in and say, “you don’t need to take notes, this will be in the handouts/minutes.” To which I always reply two things: (a) I will remember what is being said much better if I write it down than if I just read it, and (b) your handouts or minutes will not reflect my opinions or prioritization of what is being said.

    But the more fundamental point I wanted to make on your post, Jim, is that where you see a difference between content and context (a neat lexical trick, since only one letter differs between the two words), I simply see the perennial difference between writing from the user’s viewpoint vs. the developer’s viewpoint. The medical report you saw was written from the doctor’s viewpoint, using his language; you are the “user” of the service that was rendered, and you should not be expected to understand the doctor’s terminology. A company’s financial analysts are not supposed to understand SQL, but many IT-originated requirements specifications will talk about tables and joins and “where clauses” and such — same thing.

    I had a fantastic example a few months ago when an IT person described to a Marketing Communications person what she could do to her Sharepoint teamspace, and it was all written in IT jargon (and Microsoft jargon, to make things even worse). I’ll have to dig this up some day and blog it… and run away from my ex-colleagues who would know I’m talking about them.

 Leave a Reply

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>