Express yourself

I’ve just spent two hours talking with my developer about his understanding of The System for a new project. It was an excellent learning experience. I was given a lesson in technical writing for someone else. Where I thought I was being detailed, I was confusing the issues.

Now I have a better understanding of what is a good descriptive method for him. With this information I’ll be updating the existing requirements document, for my internal use. It’s an iterative process that will never end, but well worth the trip.

Documenting for Outsourced Development

I love the idea of outsourcing development. It forces you to evolve your business processes and it’s entirely in line with the code re-use paradigm found in programming:

[Try to] write re-useable code.

When you are outsourcing your development (especially when you go off-shore) this becomes:

[Try to] write re-useable documentation.

You can no longer have a casual conversation at the coffee machine* with Fred the Coder about what it was you actually meant when you said, “The system needs to save the booking”. The document must stand by itself, it needs to be portable, it needs to be re-usable.

The document creator has to provide a Rosetta Stone for the project: A record of the non-technical description provided by the client and a cohesive translation into the technical description for the development team. When questions are asked by either group, those answers should be noted and incorporated into the (next) version of the document. Even after sigining off on a final version.

If you can provide the perfect Rosetta Stone, then you will only have minimal interaction with the development team which reduces the management overheads. Badly written documentation results in far too much live translation and that leads to missed dead-lines and budget blow-outs.

*or PS3 or Kitchenette etc.