By using agile and lean principles, architects can create high-value documentation that focuses on the things that matter most.
Posted: May 3, 2022 |
Throughout my career in enterprise architecture, one of the most passionate debates (next to governance, of course) is around architecture documentation. I imagine your eyes are rolling and you're sighing deeply. You may have visions of overbearing governance requiring mounds of paperwork. But you may also be shivering as you think back to times you've had to manage, extend, support, or maintain brittle and undocumented systems. Architecture documentation matters and in many ways more than it ever has.
Traditional enterprise architecture groups follow conventional methodologies focusing on heavy view-based architecture documentation and blueprints that take months to create. I've certainly done this, and while it provided value when waterfall methods were predominant, today's agile approach is very different.
In my article Is enterprise architecture dead in digital? I touched on why lengthy architecture blueprinting, target-state development, and heavy documentation no longer work.
I'll take that a step further: These traditional practices are dated and counter to agile principles. Also, applying documentation-heavy approaches provides little value when business needs require optimizing time to market and nimbleness to change.
The challenge for enterprise architects is architecting and documenting systems in a lean way that supports agile delivery methods while ensuring documentation is not an afterthought but a part of the process from start to finish.
Agile and lean methods do not advocate forgoing documentation; they emphasize focusing on and documenting what matters. Without the right documentation, decisions go unmanaged, business risks are hidden, and designs get complex, creating brittle systems that over time cannot be scaled, supported, or extended. Architects must consistently make sure artifacts are in place when rapidly building new systems, and dealing with undocumented ones makes modernizing or growing them very painful.
The documentation that matters will vary from organization to organization and be created at different points in time. Enterprise architects must not lose sight of documentation's importance. They must narrow the focus to those artifacts bringing high value to business and technology teams, enabling both tactical and strategic needs.
[ Digital transformation doesn't happen overnight; it takes practice. Learn more about driving change in the digital transformation eBook. ]
Rather than following a strict order for when and how to document architecture, architects need to be flexible, part from traditional ways, and lead the way to an approach that works for each scenario, whether at a program, project, or product level:
A well-documented architecture can be the difference between a project that succeeds and one that fails. Documentation ensures a system is well-understood, thoughtfully designed, and can be communicated to others. Be practical in what you document, make it a part of the process, and be deliberate in what you architect, design, and solution to meet your business needs.
This article is adapted with permission by the author from Modern practices documenting architectures on LinkedIn.
