In the spirit of the Agile Manifesto, we’ve reduced our dependence on software documentation.
In some ways, this has improved our lives. And in other ways, it’s been taken too far and had the opposite effect.
In this post, we’ll take a look at the balance of these concerns in relation to a software architecture document. What is this, and when do you need it?
Download the NDepend trial for free and check out the powerful dependency graph feature to see what your architecture looks like.
Understanding the Need for Balance
The Agile Manifesto values “working software over comprehensive documentation” which isn’t to say that documentation isn’t necessary.
All too often, the baby is thrown out with the bathwater, and teams produce little to no documentation at all—including the software architecture document.
So which bits of documentation should we throw out and which should we still deliver?
Indeed, it is imperative to prioritize these deliverables with the same level of attention as any other user story. Recognizing that different organizations may ascribe distinct values to particular documents, it remains a consensus that, in the majority of cases, greater emphasis and priority should be placed on the creation of a comprehensive software architecture document.
Here’s why…
What Is a Software Architecture Document?
A software architecture document is a map of the software. We use it to see, at a glance, how the software is structured. It helps you understand the software’s modules and components without digging into the code. It’s a tool to communicate with others—developers and non-developers—about the software.
For example, a three-tier application architecture looks like this:
It kind of looks like ice cream you’d serve at a party. It has three layers. They’re all perfectly separated by a little line. It’s a relatively simple concept, but the diagram illustrates it in one quick glance.
In the real world, it might have some horizontal slices, like this:
Showing the areas like above is probably a little more helpful.
The document may include some text describing the layers. It may specify that all requests from the presentation layer must pass through the business logic layer to access data. n-tier is a widely known architectural pattern…and it’s mostly useless!
But that’s for another time. For now, let’s keep our minds on the architecture document. When do you need one of those anyway?
You Will Need an Architecture Document When…
Most applications these days are much more complicated than Neopolitan-flavored ice cream (mmmm…). n-tier architectures may have a little something for everyone, but when the rubber meets the road, our systems are much more intricate. Something like this is a bit more realistic:
Our “applications” are only part of a complex network of systems and applications. A real web of complexity! Whether we use one standard architecture or combination of many architectures, we need a map to navigate this virtual jungle.
So what about self-contained applications?
OK, if it’s a simple thing and you use a reference architecture, skip the architecture document!
Go ahead and stick something into the ReadMe. “This application uses a two-tier architecture. For information about this architecture, read this doc.”
Now, if you go back and read what’s in that link, you’ll see a problem. Even the description of an n-tier architecture isn’t exactly straightforward!
There’s a cache between the data tier and the middle tier!? Why?
Maybe there isn’t one in your world. Maybe there’s one closer to the client. The point is, that the reference architecture can only go so far in helping describe YOUR world.
If the reference architecture isn’t conveying enough information, it’s going to be useless fodder for clogging the document repository. In that case, you might as well just make sketches on the fly.
But I Can Just Sketch Up What I Need When I Need It!
I’ve had to sketch out parts of the software architecture in a pinch when one wasn’t available. Others have had to do this for me to describe their system.
Every time that happens, you have to ask:
- “Is this necessary?”
- “Isn’t there a document I can look at instead that already has this information?”
In the early stages of my career, I found myself frequently interrupting Rodney, a more experienced developer, to seek explanations about the specific section of the system I was tasked with. Rodney and his team were diligently working on a crucial project in a shared team room.
Rodney patiently walked me through the system while drawing out the architecture on the whiteboard. The interruptions caused much distraction for the other engineers in the room.
When I understood what needed I returned to my workstation in cube-land. I was all set to complete the work—and wouldn’t you know it!
A critical issue almost immediately derailed my flow. The issue took the remainder of the day to resolve. It was Friday.
I enjoyed the weekend, as we all should, and came back on Monday ready to get cracking on the ongoing work. I couldn’t remember some specific details Rodney showed me on that whiteboard the Friday before.
Wishing I had a document for that part, I grudgingly interrupted again to have a look at the diagram. To my dismay, someone erased the sketch. So Rodney had to draw it all over again.
Why wasn’t there a high-level document of the system?
Had it been designed or just coded together? Was there any plan? Who knows.
Even if it was an evolutionary design, it could’ve been documented when it was handed off or completed or at some time in its current form. Right? Ahhh…not so fast! Let me tell you about the two camps on this…
What Are the Two Camps on Documentation?
I’m going to paint a picture of two opposing points of view on documentation. This picture isn’t the way the real world works, but it seems to be pretty darn close. Sure there are some flaws and exceptions to my illustration, but please bear with me as I set the stage for the next scene.
Documentation? We Don’t Need No Documentation!
One of the camps on documentation sways to one extreme in their philosophy: don’t write documentation.
Why do they feel this way?
For one, they use emerging architectures. To document an emerging architecture, you have to keep a separate document updated along with the software. Since the software already serves as the documentation (see “The Source Code Is the Specification”), there’s no need to produce a second specification (e.g., no need to create a software architecture document since the code already expresses the architecture).
However, there’s been much debate about this view.
The central question is whether the code is the specification or the specification is something abstract. The latter argument holds that the code is only one view of the spec. An architecture document is another.
Scott Ambler makes a point for having “Just Barely Good Enough” documentation in this post about the Disciplined Agile (DA) process decision framework.
Sometimes, a simple sketch on the whiteboard is all you need in the right context. In other contexts, a software architecture document will go a long way in communicating to others (even your future self)!
Where’s the Documentation? You’ve Got to Have Documentation!
This other camp is extreme in the other direction.
They could be developing software intended for external companies. The users operating that software will require some form of guidance since they won’t have direct access to “the code itself” and may not possess the necessary knowledge to comprehend it.
They will, however, be able to read the docs. If those docs have something to tell them about interacting components, well, that might mean they won’t be calling right away when there’s a problem!
Some members of this camp learned to document things. That’s just how it’s done.
And let’s take another archetype of this cult into consideration—the “ivory tower” architect. Architects aren’t bad people to have around.
Some do at least as much implementation work as developers. But on the other end of the spectrum lie architects who deliver designs and have little to do with implementation.
Detailed design docs might be useful if you’re outsourcing the programming to keep your costs down (though I doubt this practice would achieve the goal in the long run).
The organization may require them due to regulations (or “reasons”). I’m giving a little leeway for the continued existence of comprehensive documentation, although I don’t advocate for it.
So, what should you do? Document or don’t document?
Find the Balance
Going back to Ambler’s advice, only produce documentation you can accurately maintain.
Software architectures, by definition, won’t change much over time. And because of that, the document won’t need to change much either.
A software architecture document is a high-level map. It will quickly lose value if it’s too detailed (comprehensive). It won’t be up to date, it won’t be trusted, and it won’t be used. So, make your team more aware. Lightly document your software and keep in mind that each document will have to be maintained.