I always start the solution architecture documentation as soon as I’m enrolled, and initially I used it as a well-structured scratchpad, jotting down snippets of raw information in the appropriate chapters.
Then, as I get more into the architecting activities, I start editing and enriching my original raw notes with diagrams and tables.
The document is constantly undergoing changes, and some pages describe finished parts while other pages describe my plans for part still on the drawing board.
The solution architecture document can only truly be completed very close to the project’s termination. And it required planning if consistent baseline versions of the document need to be published at various points, since it takes time to edit the material to achieve the necessary consistence in the middle of the development process.
I used to write my architecture documentation in Word, but with more and more companies using JIRA and Confluence, I have become fond of building my architecture document as a hierarchy og pages in Confluence.
This has several advantages. First of all, since each chapter has its own page, it’s easy to send links to team members and stakeholders to a particular page in my documentation to provide answers to their questions or input to an upcoming meeting.
I also find it practical that Confluence maintains a complete version history of each published change to each page. It’s easy to look back in time and see what I had written about a topic earlier in the project.
And using individual pages for each chapter makes it easier to enlist the developers in documenting relevant ears closer to their details design and implementation activities. While I’m careful not to ‘outsource’ my documentation responsibility, in some architecture documents I write very detailed specifications of interfaces, as these are used by developers of external systems that need to integrate with my solution. And the developers are better positioned to fill in many of the details, with me acting more as an editor (correcting style and phrasing to maintain consistency across the while architecture documentation.
When creating tasks and commenting on bug in JIRA I can link from the JIRA issues to the relevant Confluence pages in my solution architecture documentation. This helps testers, developers and other open the specifications with a single click while looking at the issue in JIRA. And those JIRA links also appears in the references Confluence pages, which makes it easy to jump to any issues pertaining to the architecture topic covered in each page.
Confluence also offers lots of add ons for drawing diagrams, but unfortunately most clients have non-IT people setting up their Confluence system, and they only take project managers’ interests to heart, not the architects’ and developers’. So most often, these helpful add ons are not available, and it’s usually impossible to convince the administrators to add them. They generally say no to everything, only following their bosses orders, and the bosses never speak to anyone lower than one organization level beneath them.
Finally, Confluence allows me to control access to the pages. I an grant some developers editing rights, while restricting others to only view the content, and I can hide it for people outside the project.
An argument against placing the architecture document in Confluence is that it is sometimes practical to send the whole architecture documentation in a single file to someone for complete revising – as a baseline.
However, I feel the advantages of using Confluence outweighs this drawback, and Confluence does offer a feature that exports an entire spage (all the pages that make up the complete architecture document) to a PDF file for easy and safe sharing with others.
But since Confluence can only export a single page or an entire space, it’s important to not mix architecture documentation and project documentation in the same space.
Create two Confluence spaces; one which the project managers ‘owns’ and manages, and another reserved entirely for the solution architecture pages, so you can export it as a single PDF file when needed.
And while it’s perfectly fine to link from pages in the project management space to architecture pages, never do the opposite! The project management space is a temporary thing, while the solution architecture space outlives the project, and must continuously maintained by the application maintenance team as the solution is bug fixed and enhanced throughout its entire life span.