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.