Posts Tagged: documentation

Main — Comments Off
8
Sep 10

On Documentation

George Dinwiddie:

“Why is documentation so important to us? It’s because we’re used to using documents to carry our thoughts and ideas to other people, other places, other times. Documents are good at the “other places, other times” part. Documents can be good at transporting ideas to “other people,” but it’s really hard work.”

When you are on a team that is co-located, it’s a lot easier to have a simple face-to-face conversation. Time spent creating a document and time spend understanding a document are all to waste if it ultimately falls back on a conversation to clarify the original intent.

My suggestion: start with the conversation. Then, evaluate what is lost in translation. I’m guessing you will find that the conversation is far more accurate in transporting ideas than a document — and it takes a fraction of the time to complete.

Main — Comments Off
22
Sep 09

Documentation

Jim Highsmith wrote: “Documentation is often the solution to a communications problem that can’t be corrected with documentation.”

I found this to be a good reminder. I mean, the point of documentation is a simple one isn’t it? To convey ideas and intent clearly and without ambiguity. We write it down because we can’t remember long enough or clearly enough, or we don’t trust the people we are working with enough. (“I asked for X” “I thought you asked for Y” “well, let’s go look at the document!”)

If we worked in smaller iterations (with people we trust), our need for documentation would decrease exponentially. With contract thinking (ie, everything must be written down and signed) increases project cost by 30-50%. That’s a lot of waste for a problem that is pretty easy to solve.

I suppose there is a secondary purpose to documentation that focuses on tracking the history of an item. But let’s be honest – how many times do you go back and look at project documentation after it has been released into production? In my experience, the more detailed the document, the faster it becomes irrelevant and unhelpful.

Picture 1