“We don’t need architecture diagrams! We’re doing agile!”

Where baseball is superstitious, software development is trope-filled. We love metaphors and cliches as an industry, and sometimes those metaphors or cliches get weaponized against that thing Software Developers don’t want to do.

Like architectural diagrams.

Having worked with and around effective teams, I’ve found shared understanding boils down to one or more of the following:

1. Having a vision so clearly communicated that everyone just gets it. (This is shockingly rare)
2. Working with extreme amounts of technical discipline and in very small increments
3. Clearly laying out the path through diagrams and usable documentation as a starting point

It doesn’t help the conversation that one of the pillars of agile is working software over comprehensive documentation. This harkens back to the horror stories of the enterprise documentation process. It is this pillar that lends cover to the idea that if you’re “doing agile”, you don’t need documentation.

In the same way if you know how to drive a car and you know where you’re going, or you’re following someone, you don’t need a map…

…until your GPS craps out, or you hit the first red light and get separated from your party, or a funny light pops up on your dashboard and you have no idea what that light means.

Agile is a specific context; a context where the team is co-located; the customer is readily available; there are a high number of automated unit and integration tests, and the team works in the smallest increment possible.

There are contexts where that work; and lots of contexts where that can fail pretty hard: like when you’re modernizing an existing system through a rewrite.

If you find your developers are often confused as to what they’re delivering, or they keep needing to revisit their design or implementation; then one of the first places to look whether or not the team has chosen to visually diagram how the technical pieces fit together.

P.S., It’s worth noting the agile pillar says “over”, not “Instead of”. Agile teams value working software over comprehensive documentation, but sometimes you need that documentation to get to the working software part.

2 thoughts on ““We don’t need architecture diagrams! We’re doing agile!””

  1. What I have found most of the time is that companies use “We’re doing agile” to only mean “We release software every couple of weeks” and “We don’t get bogged down in architecture or documentation” and don’t care about all that other jazz (you know, the stuff which *allows* you to release good software every few weeks).

    Now I do feel Agile is a bit too much of a buzzword now and it’s easy to fall into the dogma of “Well Agile says we have to…”, but most of the time places don’t want to have the team co-located, or the customer readily available, or have unit testing, etc. they only want to focus on the “2-week iterations” part and claim they are Agile, and that’s where the problems arise because simply having 2-week iterations doesn’t make you Agile.

Leave a Reply