Moving from an oral to a written tradition

I think people all tend to have different learning styles. Some people learn better from reading the written word, others from visual pictures and while others are more auditory learners. I think the more modalities we can incorporate the better. Especially when the problem is highly complex. I also think high quality collaboration is really really difficult. Sometimes I have seen people will opt for writing a document rather than collaborate which is an example of documentation replacing the collaboration process. I still tend to agree with the agile value system of favouring 'High quality conversations over documentation'. Because the high quality conversations and collaboration process is much much harder than documenting something after the fact. The documentation should be easy after a lot of thought, collaboration and discussion. But I agree you need the documentation in larger systems of scale and less documentation in start up style 'go fast' culture.

Thanks Tracey Oliver, really interesting thoughts. I completely agree that writing is not a substitute for talking. The article is really about _record keeping_. My point is that oral records are unreliable and unscalable when compared to written ones, and that therefore it's important to establish a culture of written record keeping (e.g. issue tracking, architecture documents etc.). I like your way of putting it that documentation should reinforce conversation. I also take the point about the maintenance burden of documentation, but I must confess that I'm not too worried about that. Even obsolete documentation can be more useful than no documentation. In any case, given that establishing a written tradition is hard I'm inclined to (initially at least) not qualify or hinder the move towards writing stuff down. It's much easier to get people to do less of something than to do more of it :-)

Hi Yaniv, Great article. I think this raises some interesting ideas. In particular, when is the right time to document our ideas? What level of abstraction should we be documenting ideas at? and how do we make sure we aren't providing multiple sources of truth such that what we document becomes outdated and untrustworthy very quickly. My opinion on this topic is that for the most part, complex problems always benefit from shared team discussions + collaboration. I think the skills of learning to have oral discussions in team environment using low fidelity techniques like whiteboard drawings and sketching helps us solve problems rapidly and end up with higher quality solutions because we value our teams input rather than just documenting our own thoughts. Documenting a solution too early can be costly. However, once we have some concrete ideas then documenting the agreed on solution at a relatively abstract level may be useful for various stakeholders like managers, partners etc. But I also think documenting low level details in relation to code implementation can become a maintenance burden and quickly become outdated with rapid software development and change. Unfortunately, we can have the tenancy to mistrust all documentation if the content is incorrect or out of date. As a developer I would often find business documents rarely matched the code. Also, I think using a document to communicate is an anti-pattern. A document should reinforce a conversation rather than replace it. If I think about the books that have withstood the test of time in IT. They tend to be books about abstract patterns or ideas. The remain relevant today because they are documenting at a level that continues to remain relevant. I really think this is the key to providing high quality documentation. Level of abstraction, timing of documentation and it should never replace conversations or collaboration. Cheers, Tracey Oliver