Too detailed and not detailed enough

This is a phrase that has recently entered my lexicon.

It was coined in a moment when discussing a design document. The offending document claimed to be a design doc but covered such minutiae as the XML schemas for ALL the messages. The level of detail was totally overwhelming for a design document, you couldn’t see the wood for the trees. You couldn’t get a sense of the intent. However, the document, as it stood was not implementable. It wasn’t so detailed that the code would be trivial; it didn’t cover every use case; it didn’t describe how the code would be structured.

An architecture document can lock down the implementation with only a few details. If it says “the system shall..” and there is only one way to do that within the reality constraints of time, money and organisational know-how then there is the choice made. Conversely, there are details that are crucial to the design. For instance the architect should always be aware of the real-world boundaries between systems; they might be formed by an OO interface or by the fact that this system is run by you and that system is run by another company.

Of course, it isn’t only architects that commit this sin. The deadly user or business analyst can make the same mistake. You should recognise it when people start saying “you should store X in the database…” when they haven’t even read Databases for Dummies.

Once you start seeing things that are too detailed and not detailed enough they are everywhere.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s