When does technical documentation violate the DRY principle?

Question

We had a project where things got in a bit of a mess a while ago because of inexperienced developers.

The main issue was the fact that the programmers rushed directly into writing the code after they have read the functional requirements. They did not stop for a moment before and think how they might implement the stuff, so they coded an implementation. After some time consumed on the task, they often realized that they have missed something and needed to back out and try another approach. The project got late, overtime was demanded etc.

That was version 1 of the app. For version 2, management decided to force the programmers into planning first, so before any code was written, the programmers had to write detailed technical specs first (I must mention here that the client does not care about these specs). A lot of the issues that occurred during coding were caught in writing the specs. Things went well for the second version.

We are now doing heavy maintenance on the second version and a lot of things get changed in the code. The team now knows well the project and gained a lot of experience, so there are no major issues. The problem now is that the changes are rather urgent and we have all this technical specifications that we must update at the same time with the code. The client does not care about the specs, he just wants his changes.

So the question is, when does technical documentation become a duplication bourdon? Also, should we lose the technical specs now that they have served their purpose or should we keep them updated?

What do you think?

Answer 1

I think that writing specs in advance has nothing to do with quality of code.

When programmers don't want to think about code structure and quality without being forced to it, this is bad. That should always be an intrinsic motivation.

You absolutely need some sort of project management system to:

• Track feature requests
• Monitor their implementation progress
• Report feature-related bugs
• Link related tasks and features together

When you have this, it is often enough basis to have an overview of the work and to serve as an input for developers. Full specs with classes and methods are not really necessary and become deprecated the moment you've finished them.

So the question is, when does technical documentation become a duplication bourdon?

When it starts to dictate implementation details than are subject to continuous change in modern agile processes.

should we lose the technical specs now that they have served their purpose or should we keep them updated?

If you need to write docs you know you will throw away later, then what's the point?

Pursue not detailed documentation but track functionality requests, features and their statuses. These won't become obsolete when you rename a class or a method.

Answer 2

Try "Behaviour Driven Development". It forces developers to think about delivering business value, and at the same time that you're "writing documentation" you're also building automated acceptance tests.

Incidentally, it's always good to mix the experience levels in a team, I'd always have at least one senior programmer (with some business/analyst skills) on a project.

Answer 3

Technical documentation becomes an innecessary duplicate when it is so detailed that it basically duplicates the written code. The technical documents should be about things like architecture and design, and the most detailed information it should have is, say, a class diagram showing the main classes of the system and the main methods of them (only the method signatures).

Answer 4

I think you've answered your own question a little. The documentation becomes a DRY burden when you're pushed for time.

Upfront design is usually a good thing for inexperienced programmers and most of the time will result in better code. However, like you say the design documentation has to be kept up to date in line with the code base.

Maybe look at incorporating some form of automated documentation and implement some standards such as templates for comments from which documentation is generated after the initial design (as recommended in the Pragmatic Programmer). Test Driven Development or Behaviour Driven Development might also be worth looking into as the tests are by definition documentation and so when new code is written so are new tests and hence new documentation.

Answer 5

It sounds to me like the only useful thing your documentation gave you was more experienced developers. Instead of gaining experience from developing the system they gained experience by 'fake developing' the system and writing it all down.

If the developers still dont have the experience to get it mostly right first time then keep up with the documentation so that they make all the mistakes in the documentation instead of the code, otherwise dump the documentation and have at it. Documenting code is pointless in most circumstances. It's out of date before it's finished and will never be read.

Answer 6

In my experience the key to overcome the potential DRY problem is to make it very easy to go back and forth from the code to the documentation.

One obvious way is to have the documentation near the code itself, a la Doxygen, but that of course works well for detailed interface documentation rather than more architectural staff. For some time I played with the idea of crosslinking the code and an internal wiki to document it, I'm sure in these tools there's room for improvement.