Architectural documentation and communication

Written by Anders Marzi Tornblad 8 June 2023

This is part 6 of the Getting into software architecture series. If you haven't read the first part, here it is: A primer for emerging software architects

When you work in software architecture, good communication skills are really important. Complex distributed systems and the growing importance of cross-team collaboration has increased the need for working communication strategies. This doesn't just imply verbal communication or presentations; it also encompasses comprehensive documentation, lucid architectural diagrams, and routine architectural reviews.

Effective communication ensures that all stakeholders, developers, project managers, or business executives, grasp not only the architecture but also the reasoning behind it. Let's dive deeper into the crucial role of architectural documentation and communication.

Shifting focus

Historically, documentation has often been neglected or poorly maintained. This can result in a confusing labyrinth of wiki pages, Word documents, or chat threads, spread across various platforms and physical locations.

Such a situation makes finding the necessary information as difficult as finding a needle in a haystack. It can become a speed bump in the development process, holding back developers who spend hours hunting for information instead of creating code. It can also create a steep learning curve for onboarding new team members, as they struggle to navigate and understand the system's architecture and rationale.

The solution is to rethink the way we approach architectural documentation. Instead of viewing it as a chore or an afterthought, we should perceive it as a continuous process that breathes alongside our system design, evolving and growing as the architecture does. This calls for a paradigm shift, from considering documentation as a static entity to always treating it as a "living document". Let's dive into some practical tips on how to achieve this transformation.

Continuous documentation

To start, embrace the concept of continuous documentation. This essentially means that the process of documentation becomes an integral part of the development cycle, rather than an appendage that is only addressed at the end (or even worse, when issues start to crop up).

Ensure that every architectural decision or system modification on a higher level is documented concurrently with its implementation. This not only keeps your documentation up-to-date, but also captures the context and reasoning behind the changes, which can be invaluable for future reference.

Implement a culture where documentation is a shared responsibility, not just the duty of a designated few. Encourage your team to add to the documentation as they work through their tasks, and foster an environment where asking questions and seeking clarification is appreciated rather than frowned upon.

Just-in-time architectural decisions

Just-in-Time (JIT) architectural decisions are another concept to incorporate. They are decisions made as late as possible, driven by up-to-date knowledge of the system and the environment. They stem from the principles of agile and lean software development, where the focus is on responding to change over following a rigid plan.

By documenting JIT architectural decisions as they are made, you capture valuable insights about the system at a given point in time. This helps to maintain the relevancy of your documentation and prevents information overload by focusing on timely and essential decisions. It also encourages active participation from team members in decision-making and documenting the process, fostering a deeper understanding of the architecture.

Manage outdated information proactively

Outdated information can create confusion and misdirection, and it's essential to manage it effectively. Regular audits of the architectural documentation can help identify obsolete or incorrect information. These audits can be part of your sprint reviews, or program increments, or done at regular intervals, depending on your team's workflow.

Develop or use a system to mark documents with a "last reviewed" date, and encourage team members to update this whenever they make changes. This gives a clear indication of the document's freshness and prompts a review if it hasn't been updated in a while.

Finally, create an environment where everyone feels responsible for the documentation. Encourage team members to flag outdated or incorrect information when they come across it, rather than bypassing it. This promotes a sense of collective ownership and ensures the documentation's accuracy and relevance.

By treating architectural documentation as a living document that evolves with your software, you can enhance its usefulness and accessibility. It becomes a tool that accelerates development and onboarding, rather than a hurdle to be overcome.

Moreover, the process of maintaining documentation becomes an opportunity for team collaboration and learning. As everyone contributes to the documentation, they also deepen their understanding of the system architecture and design rationale. This shared understanding is a powerful asset, enabling the team to make more informed decisions, anticipate potential issues, and effectively manage change.

Daily practices

How can you bring this to life in your day-to-day work? Here are some practical suggestions.

Make documentation a habit

Like most worthwhile things, effective documentation requires consistent effort. Make it a habit to document as you go, rather than leaving it as an afterthought. Include it in your definition of done – a task isn't complete until the documentation is updated, or at least reviewed.

This doesn't mean you need to write an essay for every minor change. Even a couple of well-written sentences can provide valuable context and insight. The key is to capture the essential information: what was done, why it was done, and any considerations or trade-offs involved.

Foster collaboration and ownership

Encourage everyone on the team to take ownership of the documentation. This isn't just about updating the documentation themselves; it's also about actively using it, reviewing it, and providing feedback.

Consider setting up regular review sessions where the team can go through the documentation together. This can help to catch any gaps or errors and can also serve as a learning opportunity. As team members explain their updates to the documentation, they share their knowledge and perspective with the rest of the team.

Use the right tools

The tools you use can make a big difference in how easy and enjoyable it is to maintain your documentation. Opt for tools that support collaborative editing, version control, and easy navigation. Wiki-style platforms can be a good choice, as they allow you to link related pages and keep a history of changes. Some platforms even support embedding diagrams or other visual aids, which can be a great way to illustrate complex concepts or relationships.

Encourage feedback and continuous improvement

Remember that your approach to documentation should be as adaptable as your software. Regularly solicit feedback from the team and be open to trying out new ideas or tools. Maybe the developers would find it helpful to have a glossary of terms, or perhaps the architects would like to see more diagrams. Maybe the current platform isn't meeting your needs, and it's time to look for a new solution.

By staying flexible and responsive, you can ensure that your documentation continues to serve as a valuable resource, enabling clear communication, facilitating onboarding, and supporting efficient, informed development. After all, that's what good documentation is all about.

Architecture Decision Records

The process of creating software architecture involves a series of crucial decisions that shape the system's overall structure and behavior. Often these decisions, and the context that led to them, are lost in the mists of time or buried in a flurry of emails and meeting notes. This is where Architectural Decision Records (ADRs) comes in, a technique that provides a structured way to record these decisions.

An Architectural Decision Record is a brief document that describes a major architectural decision along with its context and consequences. These documents provide insight into the 'why' behind certain decisions, helping future team members understand the rationale and preventing cyclic decision-making.

An ADR typically includes:

The decision being made.
The context or scenario where this decision is relevant.
The consequences of the decision, such as its impact on the system, or trade-offs associated with it.

The aim is not to generate cumbersome, overly detailed documents, but rather concise and readable records that give valuable insights into the architectural evolution of your software system.

Architectural Decision Log

An Architectural Decision Log is the collection of all ADRs created and maintained for a particular project or product. It offers a chronological view of all the decisions made during the system's life cycle, documenting the system's architectural journey.

This log is not meant to be static. As decisions are revisited or new decisions are made, the log should be updated, maintaining the continuous documentation philosophy we discussed earlier. This practice can be particularly helpful for onboarding new team members, enabling them to understand past decisions and their rationales swiftly.

When implemented using effective knowledge management systems, ADRs and the decision log can be easily accessed, navigated, and updated, making them integral components of an effective documentation strategy. In this way, ADRs serve as the cornerstone of your architecture's story, fostering understanding, promoting transparency, and enabling informed future decisions.

As with every aspect of your documentation strategy, it's vital to shape your approach to ADRs and decision logs around your organization's needs and culture. Encouraging everyone in the team to participate in the creation and maintenance of ADRs promotes a culture of shared responsibility and understanding, ultimately enhancing the effectiveness and sustainability of your software architecture.

Wikis and knowledge management systems

Documentation organization can make or break the efficacy of knowledge sharing within a team. The way you structure and connect pieces of information can influence how quickly and efficiently team members can find what they need. In this respect, employing wiki functionality can significantly enhance the accessibility and navigability of your architectural documentation.

Leveraging wiki functionality

Wikis have the intrinsic advantage of being able to link and cross-reference pages. This network of knowledge can greatly facilitate the process of understanding intricate systems or complex relationships within the architecture. Each page can serve as a node that encapsulates a specific topic, and the links between the pages can mirror the associations between these topics in the architecture.

Here are some practical tips on leveraging wiki functionality:

Link generously. Create links not only to pages that expand upon the current topic but also to pages that provide necessary background or context, including sources that are outside of the organization. This allows readers to follow their interest or their need for additional information.
Cross-reference effectively. When you mention a topic that is covered in detail on another page, link to that page. This can help prevent information overload by allowing readers to explore secondary topics at their own pace.
Use meaningful link text. The text you use for a link should give a clear idea of what the linked page is about. This enables readers to make an informed decision about whether to follow the link.
Categorize and tag pages. If your wiki platform supports categories or tags, use them to group related pages. This can be especially useful for large wikis where a page might be linked from various other pages in different contexts.

Knowledge management systems

While wikis are a great way to organize and share information, they are not the only option. There are a variety of Knowledge Management Systems available, each with its own set of features and capabilities. A KMS is an advanced platform specifically designed to streamline the process of organizing, distributing, and accessing information across an organization.Some of these systems are designed specifically for software documentation, while others are more general-purpose.

Knowledge management systems provide several advantages. For one, they centralize knowledge, reducing the risk of information silos. Information stored in disparate locations can lead to redundancies, inconsistencies, and confusion. With a KMS, all information is stored in one place and made available to all relevant stakeholders.

A KMS also increases productivity by enabling efficient access to information. When an employee needs to understand a specific architectural decision or access architectural diagrams, they can do so at the click of a button, saving time that would otherwise be spent hunting down information.

Stack Overflow for Teams

One concrete example of a tool that can provide KMS functionality, and that might be particularly relevant to software teams, is Stack Overflow for Teams. Much like its public counterpart, Stack Overflow for Teams enables users to ask questions and share knowledge, but within the confines of their own organization. This creates a private, secure repository for your team's questions and answers.

What makes Stack Overflow for Teams stand out from maintaining a wiki or a blog is its interactive, dynamic, and community-driven nature. It encourages the team to ask questions and actively engage with the content, fostering a community of shared knowledge and continuous learning.

In essence, embracing wiki functionality and knowledge management systems can revolutionize the way your team maintains and accesses architectural documentation. By providing a structured, interconnected network of information, you can ensure your team has the knowledge they need, right at their fingertips.

Hidden assets

When it comes to knowledge management, we often make the mistake of focusing exclusively on explicit knowledge. However, to fully leverage the wealth of knowledge within an organization, it's crucial to also acknowledge, capture, and transfer two less tangible types of knowledge: implicit and tacit knowledge. These can be more elusive, but they are equally essential to the successful functioning of an organization.

Understanding implicit knowledge

Implicit knowledge is similar to ingrained wisdom – it's the information that becomes second nature through repeated interaction with a task or process. It's the kind of knowledge that may not be immediately apparent in documentation, but is nonetheless vital for effective operation within an organization. For example, a senior developer might instinctively know the most efficient way to navigate through a complex codebase, or the best approach to debug a difficult issue. This wisdom has been developed over time and may not be explicitly stated anywhere.

To harness this type of knowledge, it's important to foster an environment that encourages open communication and continuous learning. Here are some strategies to capture and share implicit knowledge:

Mentorship programs. Pair new hires or less experienced team members with seasoned veterans who can guide them and pass on their implicit knowledge.
Regular team discussions. Create opportunities for team members to share their insights and experiences. This could be a dedicated time during team meetings or separate discussion sessions focused on knowledge sharing.
Hands-on training. Allow team members to learn by doing, under the guidance of those with more experience. This can be particularly effective for passing on skills that are more effectively learned in practice than theory.

Tackling tacit knowledge

Tacit knowledge is even more elusive. It's the kind of knowledge that's often based on intuition and experience, and it's difficult to even articulate or document. Examples might include the ability to read a room during a meeting, or knowing the best way to approach a particularly difficult client. Because tacit knowledge often involves insight into company culture or interpersonal dynamics, it can be incredibly valuable, but also quite tricky to pass on.

To capture and transfer tacit knowledge, you might have to think outside the box:

Job shadowing. This approach allows a less experienced employee to observe a more experienced colleague in action. The observer can gain valuable insights into how their colleague approaches their job, which can help transfer tacit knowledge.
Knowledge sharing sessions. Encourage employees to share their experiences and insights, focusing on the less tangible aspects of their jobs. This could take the form of brown-bag sessions or lightning talks, for example.
Creating a culture of openness. Encourage employees to openly share their thoughts, ideas, and experiences. An open culture can make it easier for employees to share their tacit knowledge and for others to learn from it.

Implicit and tacit knowledge are often overlooked in many organizations, but they are valuable assets. With the right strategies, it's possible to capture and transfer this knowledge, boosting productivity and fostering a culture of continuous learning. Remember, every piece of knowledge, no matter how small or intangible, is a building block towards a more informed, efficient, and collaborative organization.

Customizing your documentation strategy

Each organization's needs for documentation and communication is unique. One size rarely fits all. Hence, it is essential to explore different techniques, constantly ask for feedback, and continually iterate your documentation and communication strategies based on your team's preferences and your organization's culture.

Innovative techniques for communication

Embrace the opportunities that technology provides to make architectural knowledge more accessible and engaging. Don't hesitate to mix and match different methods to find the optimal mix that works for your team. Here are some examples:

Video presentations. Your lead architects could record five-minute presentations explaining complex architectural principles or decisions. The videos could be shared on your team's communication platform for everyone to access at their convenience. It's a great way to provide bite-sized learning opportunities, and it's easier for team members to rewatch and digest the information at their own pace.
Peer-to-peer teaching. Consider having junior developers present concepts to their peers. This practice helps solidify their understanding of the subject matter. Additionally, it fosters a collaborative learning environment where every team member feels empowered to contribute. As the saying goes, "If you can't explain it simply, you don't understand it well enough". This could be an excellent opportunity for your junior developers to improve their ability to not only break down complex concepts into understandable parts, but also to seek out documentation and ask for help.
Knowledge sharing platforms. Your team could also experiment with other mediums like an internal blog, a newsletter, or even a podcast. These platforms can become a rich source of insights, updates, and shared knowledge about the architecture. For instance, a monthly newsletter could include updates on architectural changes, tips and tricks for common challenges, and a spotlight on how different parts of the system work.

Remember, staying agile and receptive to change is key. Documentation and communication practices should evolve with the organization, the technology, and the people involved. By investing in clear and effective architectural communication, we lay the foundation for successful, sustainable software architecture.

Additional reading

Articles in this series: