Comprehensive Documentation for Riding a Bike is Difficult

Nonaka and Takeuchi (1995) defined knowledge as explicit and tacit. This view is of course shared with other researchers in organizational learning.

I posted about agile development emphasizing Enable Future Work -documents (as described by James Shore). That holds, but it still does not make creating quality documents easy.

Day after day engineers will arrive at work and launch MS Word alone because they need to document their work for future use. Unfortunately some will open the same tool for documenting what they are planning to do, but this is Get Work Done- documentation (as described by Jim Shore), and we are not talking about that now. At the exact same time same number of engineers will get a copy of such a document to start working based on it. By the lunch time most of them have realized the same old thing; "Just words, not even grasp of what I would have needed, half a day wasted, thank you very much."

I'm reading the Communities of Practice, by Etienne Wegner, for the second time. This time I understand a lot more, but of course I am still not fully getting it. However Etienne gives good example of two sides of knowledge, explicit and tacit. Mr. Wenger used skill of riding a bike as an example. Most of us master this skill, and we can explain it - even fairly well - in paper;






"Push some initial speed, start pedaling and just steer where ever you want to go. "






This is the explicit part, but there is one fundamental ingredient missing in the above document. How do you keep the balance? This is the tacit knowledge part, and it is extremely hard to put on paper. I give you few minutes to think about it...

OK, I tried it also while reading the book, and it reminded me about something we all have experienced.

Agile methods promote simple design to the degree that documentation is not necessary. In embedded world where you want to minimize the material cost you often end up in software and hardware design which are based on intuition. This tacit information is difficult to put on paper, just like the balancing bit of riding a bike. How many times you have been explaining your design to a peer until a bit of detail which has no meaning to you opens the design to your colleague? These obvious facts seldom get identified and reported in paper document created by the original designer individually. As a consequence the document has little or no value. This was manifested with our three-day faceoffs recently. This has nothing to do with agile development methods, since they promote simple design and light documentation?

Quite the contrary. Agile teams work well in preserving and sharing tacit knowledge among members. Daily meetings, retrospective and pair programming(co-design/debugging) are natural techniques for this. Additionally the team commits to deliver work (software/product) which is "done". Done means delivered with just enough and barely sufficient documentation. Agile team should have also shared commitment to deliver necessary documentation, which would enable them to create the documentation in collaborative way. This type of activity is valued in RaPiD7 (Ph.D. pdf), an agile method for creating documents developed at Nokia. Of course the best thing would be to have the "customer" of a document present during the creation work (or that the "customer" writes the document as Vasco Duarte proposes), but this customer for Enable Future Work -documentation is often not available at that point.

The next best thing might just be a collective team responsibility with other project stakeholders and to give it your best shot from multiple perspectives instead of single unmotivated view.