Keeping Logical and Physical Architecture diagrams updated

Question

In any software development project that involves distributed systems with multiple developers, having Logical and Physical Architecture diagrams is best practice but in my experience these diagrams always start off being well maintained at the start of a project but do not get updated as the project get released and the maintenance phases kick in.

For complex projects with a lot of distributed processes, the diagrams tend to get outdated or inaccurate really quickly even before the initial release since no one person has all the knowledge.

Given this background, I want to ask the following questions to the community:

1. How important are having accurate and up to date Logical and Physical Architecture diagrams?
2. Are there any tools and processes that can help keep them up to date?
3. Who should be responsible for keeping them up to date? How can sys admins, developers, and QA teams contribute?

Answer 1

I live in the real world with time constraints and resource issues, so I understand why most software documentation is either ignored or left out of date, but even under those conditions I absolutely insist that database diagrams are created and kept current. If it's not a usual relational model and consists of entities with documents, key-value pairs, or JSON/XML structures, then an object model of those items should also be created and maintained. If all else fails on the documentation efforts of a project, at least a database diagram and/or object model(s) will allow one to work backwards to the front-end to figure out what's going on.

There are numerous options for creating and maintaining software documents, but one of my favorites is Enterprise Architect. It's comprehensive and ties together uses cases, sequence diagrams, class diagrams, and others.

As for who is responsible for this, I consider it a team effort. Few people thoroughly enjoy doing it, but it must be done. The architect or tech lead on a project should ultimately be responsible for it, delegating tasks appropriately.