How much documentation is 'Just Enough' Documentation?

'Just Enough' is a very catchy phrase in the agile world, with every other noun is prefixed by 'Just Enough (JE)'. Sure you would have come across JE requirements, JE design, JE up front architecture, JE documentation and so on. Big problem with JE is nobody knows how much is too much. Most interesting of all is JE design documentation, if you ask 10 people you will have 10 different answers. Both the traditional advocates and agile proponents are guilty of manipulating the 'how much of design to be documented?' question to their whims and fancies.

Traditional Approach to Design Documentation

In the waterfall projects, architects use to come up with 200 pages of design doc or a flurry of UML diagrams only to see that they become at least slightly out dated even before the first line of code is written. That's because the architect worked in isolation and didn't collaborate with the development team while creating the design and document. When the development team starts coding, they are confronted with a few practical problems that the document is completely dormant about. When the design doc doesn't answer questions, they just keep it aside. This is the situation the day coding starts. Better not to talk about the design documentation the day coding ends. Design and coding would have gone just like a divorced couple, on 2 opposite directions.

Architect will say that's the development team's problem and they don't know how to implement my design. Development team never cared the architect or whatever she says in the design document. Finally the single version of truth is your code only ; People who join the project mid way or who maintain the software will have to start from the code doing reverse engineering.

Not to say that if you have a big but 'live' document, you can conquer the software easily. It's still a combination of many factors like reading the doc (Just Enough reading??), walking through the code and collaborating with the existing or old team members. Sad reality is these 3 factors never meet eye-to-eye

Agile Approach to Design Documentation

Agile proponents are equally guilt. Of the 4 declarations in the agile manifesto, they like one thing for sure- "Agile values working code over comprehensive documentation". This is great, but the problem is how the agile teams understand and interpret this. They interpret this as "Agile values working code over documentation". Result is obvious, there will be zero documentation. You will have only code- no matter whether you are from business or IT. That's not a great situation to-be in either.

Do we need to strike a balance?

A few high level diagrams would always be helpful. The chances of the documentation becoming obsolete are very remote because they are at a "high level". Capturing the big picture is mandatory for any future reviews and understanding. Following approach may help

• One "all-in-one" systems diagram in which you depict all the other systems and users interact with your software. This will be great for business people and some one who just starts with your software

• One Components diagram in which you depict all the components of your systems and how they related to each other. Your software system may contain a smart client app, a web service and an admin web interface or an unattended windows service. You put them all in one diagram showing the inter-dependencies and relations. This will be useful for "tech savvy" business people besides hard core techies.

• Class diagrams for each component in your system- this will give a great deal of information to  techies who are going to maintain the software

Apart from the 3, you may go to lower levels of design documentation depending on the complexity and/or maturity level of your team. But mostly lower level design documentation is a wasteful exercise because it will get outdated every other day. With concepts like refactoring and automated unit testing, it's almost next to impossible to keep the documents 'live'

More over with too much lower level design documents, you treat your developers not like developers, but as "Code Entry Operators" which no developer likes. One practical approach is each team defines their level of design documentation for their project and they adhere to it. "Just Enough" is always to going to be subjective, but we may conquer it with some pragmatic approaches like capturing the big picture as we discussed above