A while back, I worked with a team in a cube bullpen to help mentor them primarily in test-driven development (TDD). Their goal was to deliver a decent-sized web product–not huge, not trivial.
The first time I paired with the programmer nearest the bullpen opening, I noticed a large framed document on a nearby cube wall, outside the bullpen, and asked what it was. All I could tell from that distance was that it was a highly detailed diagram of some sort.
I asked my pair about the document.
“It’s our class model.”
“How do you use it?”
“We don’t. It’s out of date.”
Of course it was. We went back to building code.
When we took a break, I walked to the diagram. Sure enough, it was a UML class model–with gobs of detail. Public methods, attributes, private methods, annotations on the associations, attribute types, return types, and so on, all specified in what looked like a couple hundred classes. Arrows all over the place. As I previously mentioned, the document was framed (albeit cheaply), which meant that the model itself was enshrined in a protective layer of glass (plastic?).
The framed model sure looked pretty! And it no doubt looked quite impressive to any non-technical observer (such as a vice president): “They built all that!”
Of course, the team that actually produced the detailed model no longer found it useful. During the remainder of my engagement, I never once saw a developer look at the diagram. And most amusing, when I took my one visit to inspect the model, a closer look revealed that the programmers had briefly attempted to keep the model up to date. On the surface of the glass, there were various scribbles and attempted modifications, all written directly on the glass.
Your software is special, but your design models are not, and they change rapidly. Don’t enshrine your design.