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?

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, we should prioritize those deliverables like any other user story. Some organizations will place a higher value on certain documents than others. Nearly all should put more priority on creating a 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 combinations 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 in your world. Maybe there’s one closer to the client. The point is, 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?”

Early in my career, I had to keep interrupting a more senior developer, Rodney, to ask him to describe the part of the system I was working on. He and others were in a team room working on a critical project.

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 crackalackin’ 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.

For one thing, they might be producing software for other companies. Those who run that software will need something to go by. They won’t have access to “the code itself” and probably won’t know what they’re looking at anyway.

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.