Documentation driven design. Your experiences.

Question

I noticed this project (pitz) that is being written first with the documentation, then tests, and finally code. Has anyone else tried this "Documentation driven design" and if so, what are your experiences with it?

Answer 1

I guess it depends upon what level of documentation is being written. Capturing key requirements, features, etc. is a good idea to do before diving too deep into code. It helps to plan and scope out the work.

On the other hand, writing too much documentation (very detailed design specs etc.) before writing tests/code is often a bad idea since invariably the documentation goes out of date as soon as you start to write code. There is then a "technical debt" task to update the documentation - so in the end you do the detailed documentation twice (or more likely you never get around to updating the documentation and it remains out of date and somewhat useless!).

Answer 2

Well in many ways documentation and specification share many of the same attributes and concepts. They describe what something does and how to use it.

I would hope you're not unfamiliar with the concept of writing specifications before code :)

Answer 3

it is not unusual in waterfall methodologies to write the user manual concurrent with the screen designs

which works fine when the target is not moving

this is easiest to do when you're writing something for yourself, or solving a static problem in a well-understood domain

Answer 4

Yes, I've done it a couple of times, the most succesful of which was when we were developing a library for use by another part of the organisation, with whom we had erm, "issues". To avoid endless & fruitless arguements, I wrote up the whole library API in the same form that Microsoft use to document the Win32 API before we implemented it.

The presence of the document allowed the discussions between the two groups to become more structured, and though the API spec was significantly changed over time, we did finally get the implementation out the door on schedule.

So if you are going this route, I recommend finding some existing documentation you like and modelling your own on it.