This is a loaded question. Is there a better way? Maybe. It is almost certainly not any easier, though. Likely takes longer and requires as much investment from the reviewers as it does from the authors.
I confess I'm fond of Literate Programming for this, though, I have never tried introducing it in a company. My hunch is it would take too long. By far.
Even documented software often takes too long. Same reason you don't plot out how you are going to win a ballgame. Outside of "score more points than you allow", the plans are almost all exploratory and reactive. Solidifying that into a document is dangerously slow.
I've long dremead of a architecture view that was zoomable, zooming in enough would end up on the actual code, but zooming out a lot would show you app server +database basically.
This would be incredible. No reason zooming out can't also show you stuff like load-balancers, message queues, firewalls, and their config/infrastructure code.
I too have had this dream. It's like a Realtime stragedy game, you have a minimap where you make big movements around the map, zooming in to perform some micromanagement on individual units. Zooming in further to directly edit there AI.
I confess I'm fond of Literate Programming for this, though, I have never tried introducing it in a company. My hunch is it would take too long. By far.
Even documented software often takes too long. Same reason you don't plot out how you are going to win a ballgame. Outside of "score more points than you allow", the plans are almost all exploratory and reactive. Solidifying that into a document is dangerously slow.