Who ever needs the information writes the documentI've heard many times the old adage: "You need to document it properly first to be able to code it later. That's why you need architects and designers that prepare the documents that programmers will base their work on."Surely the people that say this don't mean "spend more money/time than you need to satisfy the customer", but that's what they get.Think about it: if you write a document in 1 hour and you need to share that knowledge with 2 other people you will have to spend at least another hour explaining that document to those 2 people (I'm not even counting in the document reviews). Meaning that in a good scenario you will spend 3 hours to imperfectly transfer knowledge to 2 people that you could by talking to them face-to-face (and close to a whiteboard) during one hour.Why you need to spend time talking to people even after writing the document is that people are not perfect writing documents nor understanding what someone else wrote. When people write (very much like I'm doing now) they have their own context, their own knowledge, their own assumptions, etc. Not all those get written (it would simply take too long and most of them would not be relevant anyway), many times some critical knowledge does not get to the paper. When that happens the reader will not be able to understand the text without talking directly to the writer and spend time discussing some of the not so obvious knowledge behind what is written.All this takes time. That's why in my projects I try to push for a simple rule regarding documentation:Whoever needs the information writes the documentWhy? The person who writes the document (the one that needs the information) will go through the process of understanding the information while she writes the information (this is the main purpose of this rule) The person often needs the information because she interacts with the project team, in this situation writing the document (and all the information exchange with the team that comes with that) will also help that person commit to help the team solve the issues she will be asking them to solve In the process of researching the document the person shares a lot more information with the team than what gets written. This is important because both the writer and the team get to share information they would otherwise not.Trade-offsDocumentation can have bigger impacts in the projects than we normally think. Bear with me while I try to explain this. Let's take a simple (but not simplistic) method to analyze the trade-offs that we have in a project. In the project management literature we often read about the "triangle" of Quality, Scope and Resources (now that's a simplistic model...).In reality we spend our time in software projects doing the following:Quality work: including testing, reviewing documents, discussing bugs, etc.Feature work: implementing, thinking about features, finding which requirements to implement, reworking (fixing bugs), etc.Documentation: writing information down for generations to comeFace-to-Face communication: exchanging information, team building, etc.Normally in software projects we hear about trading Quality for Features/Scope. This view comes from the fact that we are forgetting that we can actually trade other things out before we have to trade out quality. In fact we can trade out for example documentation or face-to-face communication.I suspect that you are just now realizing that you've actually done that before: you've traded out face-to-face communication or even documentation to spend time with features or quality, but it probably happened by default, i.e. you did not make that trade-off being aware of the consequences, you just did it because it seemed natural at that time (and it probably was).The lesson here is that you must plan what you want to trade-off in a software project so that you know what matters when the time comes to drop something (and that time _always_ comes!), if you don't plan the trade-offs you will end-up trading-off quality like most people out there - even when you could be trading off documentation, especially the one that delivers no value to the customer.Agile DocumentationAgile methods are light on documentation because the people behind those methods have recognized (after many years of experience) that documentation should be used like salt: with moderation.Time to cut down on the salt! ;) Posted by

Who ever needs the information writes the document

I've heard many times the old adage: "You need to document it properly first to be able to code it later. That's why you need architects and designers that prepare the documents that programmers will base their work on."

Surely the people that say this don't mean "spend more money/time than you need to satisfy the customer", but that's what they get.

Think about it: if you write a document in 1 hour and you need to share that knowledge with 2 other people you will have to spend at least another hour explaining that document to those 2 people (I'm not even counting in the document reviews). Meaning that in a good scenario you will spend 3 hours to imperfectly transfer knowledge to 2 people that you could by talking to them face-to-face (and close to a whiteboard) during one hour.

Why you need to spend time talking to people even after writing the document is that people are not perfect writing documents nor understanding what someone else wrote. When people write (very much like I'm doing now) they have their own context, their own knowledge, their own assumptions, etc. Not all those get written (it would simply take too long and most of them would not be relevant anyway), many times some critical knowledge does not get to the paper. When that happens the reader will not be able to understand the text without talking directly to the writer and spend time discussing some of the not so obvious knowledge behind what is written.

All this takes time. That's why in my projects I try to push for a simple rule regarding documentation:

• Whoever needs the information writes the document

Why?

1. The person who writes the document (the one that needs the information) will go through the process of understanding the information while she writes the information (this is the main purpose of this rule)
   
2. The person often needs the information because she interacts with the project team, in this situation writing the document (and all the information exchange with the team that comes with that) will also help that person commit to help the team solve the issues she will be asking them to solve
   
3. In the process of researching the document the person shares a lot more information with the team than what gets written. This is important because both the writer and the team get to share information they would otherwise not.
   

Trade-offs

Documentation can have bigger impacts in the projects than we normally think. Bear with me while I try to explain this. Let's take a simple (but not simplistic) method to analyze the trade-offs that we have in a project.
In the project management literature we often read about the "triangle" of Quality, Scope and Resources (now that's a simplistic model...).
In reality we spend our time in software projects doing the following:

1. Quality work: including testing, reviewing documents, discussing bugs, etc.
   
2. Feature work: implementing, thinking about features, finding which requirements to implement, reworking (fixing bugs), etc.
   
3. Documentation: writing information down for generations to come
   
4. Face-to-Face communication: exchanging information, team building, etc.
   

Normally in software projects we hear about trading Quality for Features/Scope. This view comes from the fact that we are forgetting that we can actually trade other things out before we have to trade out quality. In fact we can trade out for example documentation or face-to-face communication.

I suspect that you are just now realizing that you've actually done that before: you've traded out face-to-face communication or even documentation to spend time with features or quality, but it probably happened by default, i.e. you did not make that trade-off being aware of the consequences, you just did it because it seemed natural at that time (and it probably was).

The lesson here is that you must plan what you want to trade-off in a software project so that you know what matters when the time comes to drop something (and that time _always_ comes!), if you don't plan the trade-offs you will end-up trading-off quality like most people out there - even when you could be trading off documentation, especially the one that delivers no value to the customer.

Agile Documentation

Agile methods are light on documentation because the people behind those methods have recognized (after many years of experience) that documentation should be used like salt: with moderation.

Time to cut down on the salt! ;)