How to document an enterprise architecture: 5 modern practices

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.

Enter agile delivery and lean methods

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. ]

Best practices

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:

• Document what matters and when it matters. Not everything needs to be documented at the beginning. Architectures and corresponding designs can be fluid, especially when testing new capabilities, in pilot mode, or building a new system. Some can be transient, while others need to be permanent, so start with working code, the minimal set required, and extend over time.
• Capture all architecture decisions from the very start. Organic architecture is not architecture. Architecture is deliberate, emergent, and intentional. It avoids situations where you question why a system and its components are designed a certain way and maintains clarity on what forces result in a specific approach. Documenting decisions allows the organization to look back and verify that the solutions continue to meet business needs and helps when extending or refactoring them.
• Track architecture debt to keep a current, well-managed record of what needs to be addressed and facilitate product-level planning and backlog grooming. Undocumented technical debt must be avoided at all costs.
• Document architecture as a part of the process and not as a catch-up activity nor when there's time because there's never time. Define "design complete" as completing an architecture, its design, and the required artifacts. Just as untested code introduces business risk, so does an undocumented architecture.
• Maximize automation of artifacts. While some artifacts require manual work, it is entirely possible to automate creating others, including context and interface diagrams, process flows, service and API catalogs, and infrastructure diagrams. Leveraging self-documenting techniques and automation keeps artifacts current based on what was built and what's running.

Wrap up

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.