Documentation is often thought of by software developers as chore they have to go through which gets tacked on to the end of a development process.
At Bindon.net, we think of documentation as the key to hapiness and ever-lasting life.
Ok, perhaps I'm exagerating, but only slightly.
Documentation allows us to operate on software projects with minimal dependency on individual programmers, which in turn allows us to virtually eliminate ego and personality from the development process.
Documentation also saves us from having to repeat ourselves, and from having to repeat our mistakes.
Documentation is precisely what elevates today's businesses above the level of an oral tradition, and allows a business to have its own inteligence and capacities, above and beyond the inteligence and capacities of any of it's individual staff.
At Bindon.net we love documentation so much, we even have "Documentation about Documentation".
"Some of you may not be ready for that yet, but your kids are going to love it." (Marty McFly)
(draft 2, 10 October 2004, Andrew Bindon)
Today everyon working on the project we are working on is working from the same page. We know this for absolute certain because we are working from the SAME DOCUMENTATION. It is updated dynamically and ongoingly by all team members with sufficient level of authorisation. We all refer to it in all the work we do. It is single-sourced on the companies intranet. There is no question that we are aligned on what we are doing, because we are all working from the basis of the same specification document.
A group of people working together on something can achieve things which people working in isolation cannot achieve. It is not for no reason that our ancestors hunted in packs. Documentation is not the only way to achieve group intelligence. Some nomadic tribes have sustained themselves with an “oral tradition”. In the oral tradition, wisdom is passed from generation to generation via the spoken word, very often in the form of fables and folk tales. Weekly seminars in which team members share new insights they have realised with other team members can be useful.
However the value of “written tradition” has been understood since at least the time of the pharaohs. When the complexity of a subject reaches a certain size, an oral tradition starts to fail in being able to communicate powerfully everything that is useful. We start to have to spend so much time simply repeating what we said earlier that day or yesterday or last week. And in order to be able to repeat it, we have to be able to REMEMBER it. As a subject reaches a sufficient level of complexity, remembering all the pertinent correlations at just the right moment becomes increasing difficult. Written (stored in some way) documentation helps deal with this problem.
When I document something, I become clearer about it, my understanding increases. I start seeing connections between the parts of the whole that I hadn’t seen before. I start to be able to see the whole of something, not just the part of it I am currently engaged in working on.
When I understand the whole that I am working to produce, it is more satisfying to be working on the part I am currently working on. Because I am able to do this work in the context of the whole that it is contributing towards making.
We are going to be more effective if we know where we’re going before we set off going there. How can we tell if we know where we are going? Do we all agree about this, at least as of today? Once it gets written down, where we are going becomes VISIBLE. So this is another related key distinction about the reasons for having documentation: PROJECT VISIBILITY.
EXISTENCE, COMPLETION and INTEGRITY. (But that’s a whole other story.)
The key distinction about development project specification documentation is that it is DYNAMIC. That is to say, if specification documentation is any good, it changes as the project progresses. Specification documentation is not a one time deal. It is not “we write the specification and then we stick to it in the face of all reason”. The value of specification documentation is NOT that it “nails people down” with respect to what it is that they want. The value is that it CLARIFIES what it is wanted, what the current status of the project is and where we are currently headed next and after that at any given moment during the project process. Dynamic documentation is “valid today”… and if it is really dynamic (really useful) it is ALWAYS “VALID TODAY”, because it is kept up to date on a daily (ongoing moment-by-moment) basis. Making specification documentation provides an opportunity for people involved in a project to get clearer about what it is that they want, or in the case of the developer, what it is that they are building.
As a project progresses, there is a greater and greater cost associated with making alterations to the specification, but this does not mean that they should not be made. It is very difficult at the beginning of a project to know completely how every aspect of it will progress, so a certain amount of flexibility with this is needed. Using documentation in this “limiting” kind of way discourages people from engaging in it at all, so it is much better that we have documentation, and then change it every few days to account for the new understanding we have of a requirement, or a new solution we have discovered to a problem. In this way, documentation becomes a publicly available statement of where we are CURRENTLY heading in the project. It allows us to be working not only so as to achieve the next milestone, but arrive comfortably at our destination. It is able to achieve this, because it clearly delineates what our destination is.
Here are a few examples of why dynamic documentation is useful: (To be filled in.)
Given that the main point of having documentation is the it supports a shared understanding of a project, coordinated action, consensus amongst those working on a project, and clarification of issues, it is absolutely critical that the documentation is easily accessible by the people involved. Dynamic documentation, that is to say documentation that is updated on an ongoing basis needs to be accessible. If I am going to look at the documentation as @ now, I need a way of doing that. An intranet / extranet is an ideal way of achieving this.
Printed versions of documents can be useful for meetings or for reading, but should typically be destroyed regularly (at least as regularly as the documentation is being updated.) In other words, shared public and accessible documentation is just another way of saying that the documentation is dynamic. These are really 2 aspects of the same issue.