Think of good practices in waste reduction, since you have scarce resources.
Use architectural frameworks as guidance to good practice, don’t bother creating all kinds of artefacts that nobody in your teams will miss.
Regular architecture reviews and code reviews will do much to ensure quality and share knowledge within your teams. Run them effectively.
Boxes and lines are nice, can even be aesthetic. But unless they shed light on otherwise unclear semantics, boxes and lines can be wasteful.
To be effective, your architecture models must capture and maintain essential knowledge about your system, this includes user stories and issue and feature databases, and source code!
When you’re clear on what your team should produce and maintain and the scheduling, then and only then look for cheap tools that can help.
Here is a take:
You can get away with a few simple documents:
- screen flows: use a simple drawing tool, or scan sketches into image files
- user stories (or use cases), it’s your software promise to its users
- design principles, essential Do’s and Dont’s for your technical folks
- design trade-offs, technical decisions and their limits
- contracts (internal and external APIs for your modules)
- business rules, the knowledge-bearing decision points in your system
In the list above, one can argue whether business rules should really be included in an architecture documentation. The same goes for screenflows and user stories. But when running on tight budget, decisions tend to be made on the flight and built into the code, people rarely go back and update otherwise stale diagrams.
User stories are created at the initiation stages, but over time they are superseded by the issues logged against iterations of the product. The features could change shape as a result of the learning process, to a point where the initial architecture might become significantly altered.
What happens is that, over time, knowledge increasingly migrate to the issue database and the source code, and it stays there. That is the rationale for considering the issue database as part of the architecture documentation.
Some tips:
- Avoid waste: any document that doesn’t hold unique information is a waste
- Be economical with the boxes and lines, focus on contracts and boundaries
- Use spreadsheets to capture your architecture principles, trade-offs, business rules
- Maintain an active issue and feature database. You would probably be doing this anyway, but I’m saying that consider it an architecture documentation artefact
- Encourage in-code documentation, enforce through standard quality checking and code reviews
- If your tool-kit permit it, (thinking JavaDoc) generate documentation from source code and include them in your code review sessions
There are more tactics for capturing and maintaining knowledge within your organisation, but that is perhaps a topic for another post.