Here at our company we hear everyday amazing and interesting things. Once someone said "Let's move these documents to wiki" - they were talking about a few of the dozen or more documents in one particular project.When asked why, they replied: "Because we want to 'maintain' these documents".Hum... If that is the case why keep any documents outside wiki then? And why do you need documents that you do not plan to maintain?(NOTE: documents that need to be delivered to customers are a totally different category, I'm talking here about project-related documents that are used only inside our company)Why, in general, do we write documents in software development projects that we don't want to maintain? Here's a few guesses:- Because management says it should be done...- Because Rational Unified Process (RUP) says so!- Because everybody does it!- Because we've always written them!- Because the person who writes them would be out of a job if we did not write them!We seldom hear this:- Because it adds value to our customers!Why is it so? My guess is: because those documents that add value to our customers require 'maintenance'. Those are documents we want to keep always up to date as they will go to customers. Or customers expect those documents to be kept up to date for any other reason. Here is the key: the documents you don't update are normally documents that add no value to your customers. So, once you write them then you are done with that document and you don't need to touch it again.There are valid reasons for writing documents that don't get updated. One example is that writing helps clarify ideas, and the process of writing a document may help you structure your thoughts and develop your original idea to a certain point.One example I often like to quote is the Vision document. I always keep the Vision documents I write 2 pages-long, and I make myself write that document for every major project.By writing that document at the beginning of the project (even if I don't update it later) I make it clear to myself and the project team what this project is all about. Keeping to a maximum length of 2 pages also makes me clarify and synthesize my ideas (or the group's ideas) at the same time making me cut down on the superfluous things for that product/project.I don't update that document later, but the actual process of writing the document helps me in my work. In my book that's a document worth writing!In other projects, however, that's not what I see as the role of documents. People still write documents thinking that the mere fact of writing that document, or even worse, the fact that document exists will make their project a success. To add to the problems with this, many people write documents that are not supposed to add any value anywhere in the project, they just do it because the process says so!To avoid writing documents that you don't really need, ask yourself these questions:1- To whom am I writing this document? Would it be better if I talk to them ?2- Would it be cheaper to explain my ideas to the target audience? (some documents are written for 5 hours to be read by 2 people, it would be much cheaper to just talk to those people and maintain a good communication channel then spending 5 hours writing that document!)3- Am I working in an environment where people don't trust me? (if you are you have two options: a) cover your ass by writing a document and getting it signed off, b) quit and find a better job. I would go with the second option).Consider also the required quality for the document you are writing:1- How much time do you think a person has to read this document? (probably they have half the time you think: just ask them. 5 minutes: 1 page, 10-15 minutes: 2 pages, more than half-hour: 5-10 pages - please don't make it longer than 10 pages...)2- How accurate does it need to be? (not at all: don't review it!; somewhat: write it and explain it to someone who does not know about the content but could tell you if it is accurate in their view; very accurate: are you sure you have enough money and time to do this?)Writing good quality documents is difficult, but more difficult is to write the right documents. Think twice before you decide to write one. Posted by

Here at our company we hear everyday amazing and interesting things. Once someone said "Let's move these documents to wiki" - they were talking about a few of the dozen or more documents in one particular project.

When asked why, they replied: "Because we want to 'maintain' these documents".

Hum... If that is the case why keep any documents outside wiki then? And why do you need documents that you do not plan to maintain?
(NOTE: documents that need to be delivered to customers are a totally different category, I'm talking here about project-related documents that are used only inside our company)

Why, in general, do we write documents in software development projects that we don't want to maintain? Here's a few guesses:
- Because management says it should be done...
- Because Rational Unified Process (RUP) says so!
- Because everybody does it!
- Because we've always written them!
- Because the person who writes them would be out of a job if we did not write them!

We seldom hear this:
- Because it adds value to our customers!

Why is it so? My guess is: because those documents that add value to our customers require 'maintenance'. Those are documents we want to keep always up to date as they will go to customers. Or customers expect those documents to be kept up to date for any other reason. Here is the key: the documents you don't update are normally documents that add no value to your customers. So, once you write them then you are done with that document and you don't need to touch it again.

There are valid reasons for writing documents that don't get updated. One example is that writing helps clarify ideas, and the process of writing a document may help you structure your thoughts and develop your original idea to a certain point.

One example I often like to quote is the Vision document. I always keep the Vision documents I write 2 pages-long, and I make myself write that document for every major project.

By writing that document at the beginning of the project (even if I don't update it later) I make it clear to myself and the project team what this project is all about. Keeping to a maximum length of 2 pages also makes me clarify and synthesize my ideas (or the group's ideas) at the same time making me cut down on the superfluous things for that product/project.

I don't update that document later, but the actual process of writing the document helps me in my work. In my book that's a document worth writing!

In other projects, however, that's not what I see as the role of documents. People still write documents thinking that the mere fact of writing that document, or even worse, the fact that document exists will make their project a success. To add to the problems with this, many people write documents that are not supposed to add any value anywhere in the project, they just do it because the process says so!

To avoid writing documents that you don't really need, ask yourself these questions:
1- To whom am I writing this document? Would it be better if I talk to them ?
2- Would it be cheaper to explain my ideas to the target audience? (some documents are written for 5 hours to be read by 2 people, it would be much cheaper to just talk to those people and maintain a good communication channel then spending 5 hours writing that document!)
3- Am I working in an environment where people don't trust me? (if you are you have two options: a) cover your ass by writing a document and getting it signed off, b) quit and find a better job. I would go with the second option).

Consider also the required quality for the document you are writing:
1- How much time do you think a person has to read this document? (probably they have half the time you think: just ask them. 5 minutes: 1 page, 10-15 minutes: 2 pages, more than half-hour: 5-10 pages - please don't make it longer than 10 pages...)
2- How accurate does it need to be? (not at all: don't review it!; somewhat: write it and explain it to someone who does not know about the content but could tell you if it is accurate in their view; very accurate: are you sure you have enough money and time to do this?)

Writing good quality documents is difficult, but more difficult is to write the right documents. Think twice before you decide to write one.