A software product's lifecycle does not end with its release; it continues with updates, bug fixes, and improvements. The maintenance phase of a software product is an ongoing process that requires constant attention and investment.
Without proper documentation, software development becomes complex and costly, even if you are using professional software development services. The absence of good documentation leads to increased costs, longer development cycles, and unhappy customers. The lack of documentation alone contributes 21.5 % of additional costs in understanding the code.
Documentation is vital to a software product's success; it serves as a guide for developers and other project stakeholders. arc42, an industry-standard documentation template, outlines the essential aspects of documenting a software system.
Let's review what arc42 is and why it should be used commercially.
What is arc42?
arc42 defines itself as "All you ever need to construct, communicate, and document your software architecture."
arc42 is a popular open source template for creating and maintaining architecture documentation for software systems. It was developed by Dr. Gernot Starke and Dr. Peter Hruschka in 2005 and is constantly maintained and updated by a community of architects.
The template covers all aspects of software architecture, including context, requirements, structure, behavior, deployment, cross-cutting concepts, and quality attributes. The standardized structure allows for accessible communication of architecture-related information among development team members, stakeholders, and managers.
arc42 is a process-neutral, technology-independent template that takes a practical and pragmatic approach to software architecture documentation. It is designed to adapt to different projects, industries, and organizations quickly.
Many well-known companies use arc42 to maintain technical documentation of their projects, including SAP, Siemens, and T-Systems (IT division of Deutsche Telekom), benefiting a range of industries such as banking systems, fintech companies, telecom operators, network providers, automotive manufacturers, healthcare software. arc42 was also adopted in the public sector, for example, in German government agencies and some European Union’s IT projects.
Why Use arc42 in a Commercial Setting?
Software products are created and maintained for profit; time and resources are of the essence. arc42 helps optimize resources and the time spent maintaining parts of the system.
The problems that SMBs and large organizations face regarding software architecture documentation are massive, and some of the problems that arc42 solves are:
- High costs and time spent on understanding complex systems
- High risk for business-critical systems with complex architectures.
- Limited scalability for future updates and improvements.
- Difficulty in managing dependencies, interfaces, and integrations.
- Dependency on individual team members for knowledge transfer
- Lack of visibility into a software product's current state and future direction.
- Inadequate documentation for security, performance, and other quality attributes.
- Communication issues between team members, stakeholders, and managers.
- Absence of a central source of information for fundamental decisions and project planning.
- Lack of documentation standards and consistency leads to confusion, ambiguity, and errors.
- Inability to track changes and updates to the software system over time.
arc42's standardized structure and comprehensive coverage of all aspects of a software system help organizations avoid these problems and improve the overall quality of their products.
arc42 vs code-as-a-documentation
Code is usually considered the ultimate source of truth for a software system and contains valuable information about the architecture.
The code is not self-explanatory and requires additional documentation to understand the design decisions, trade-offs, and rationale behind it. arc42 complements the code by providing an accessible and consistent architecture communication and documentation structure.
Using code as documentation increases the risk of knowledge loss, especially when team members leave the project. arc42's standardized structure and documentation make it easier for new team members to onboard and understand the system.
Code does not provide high-level information about the system's context, requirements, or quality attributes. arc42 captures these critical aspects and provides a holistic view of the software system.
arc42 enables non-technical stakeholders to understand the system's architecture without diving into complex code and technical jargon. The standardized structure and visual representation make it easier for managers to grasp the system's current and future direction.
Best practices in documenting IT projects
There are a few steps and practices that can help ensure that your documentation is well-maintained, useful, and supports your organization’s goals.
- Define your audience. Who will be using this documentation, and what is its purpose? In the case of many IT projects, documentation will be used to describe an overview of the whole system and important decisions, to onboard new employees, and to store relevant facts for future development.
- Start documenting your project as soon as possible. You may be tempted to avoid documentation as a trade-off to focus on rapid development. This will inadvertently cause some decisions to slip undocumented and require more time and effort in the future to retrace your steps and reconstruct the “why” and “how” of your system modules.
- Update the documentation often. IT project documentation should be a “living document” that benefits the whole team. If any new architectural decisions were made, a significant problem got solved, a major feature has been delivered, or a potential risk has appeared - all of those cases should be documented immediately, as any other related to the system architecture. The easiest way to approach this is to include documentation as a part of Definition of Done, or as a part of preparation for Retrospective Team Meetings.
Involve the whole team. Documentation shouldn’t be a responsibility placed solely upon the Project Manager. Including software developers, QA specialists, UX/UI designers, or other experts will bring a broader perspective and allow us to capture an accurate picture of the system and the network of many decisions and dependencies. This will also increase the likelihood that the documentation will be useful to the team and a tool that stakeholders use when discussing the next steps.
When to use arc42?
Not all projects require arc42; it is best suited for complex, long-term projects with high business impact. Here are a few criteria to help decide if arc42 will be helpful in a given project.
Project size and complexity
The more complex and substantial a software system is, the more documentation is needed. As a rough guide, projects with 50k+ LOC (Lines of code) or more will likely benefit from arc42. The number of external interfaces, dependencies, and integrations also affects complexity.
Business impact
Projects with high business impact or criticality require arc42 to mitigate business risks and ensure the system's stability, scalability, and maintainability. The cost of downtime or failure in such systems is usually high, making proper documentation essential.
Longevity of the project
Projects expected to have a long lifespan or require maintenance over an extended period are ideal candidates for arc42 documentation. arc42 provides a central source of information for ongoing maintenance and updates, reducing the time and resources spent on understanding the system.
Team size and composition
Teams with more than five members or frequently onboard new members can benefit from using arc42. The standardized structure and comprehensive coverage of arc42 documentation make it easier for team members to understand the system and collaborate effectively.
How to Use arc42?
arc42 is a versatile documentation tool that can be adapted to different projects, industries, and organizations. Here are some steps for applying arc42 to your team.
- Familiarize yourself with arc42 documentation.
- Decide which sections of arc42 are necessary for your project and team.
- Create a template for architecture documentation based on the necessary sections.
- Assign team members to work on specific sections of the documentation.
- Continuously update and review the arc42 documentation throughout the project.
- Use arc42 as a guide for decision-making and communication within your team.
The above steps can be adjusted to fit your team's needs and goals. Remember, arc42 is an architecture template that can be tailored to your project's requirements.
arc42 can be used with various project management methodologies and approaches, and is tooling-agnostic. For teams using a project management tool, such as Jira or Trello, an arc42 template may already be available. If not, you can create your template and import it into the tool.
What Does the arc42 Template Include?
arc42's standardized structure covers all aspects of a software system, including context, requirements, architecture, and quality attributes. Here are the main sections included in an arc42 template.
Goals
Goals describe the objectives and success criteria for the software system. They provide a clear understanding of what the system is intended to achieve. Quality goals are critical as they guide the architecture decision and design.
Constraints
Constraints define limitations or boundaries that impact the system's design, software development, and implementation. These can include technical, business, or organizational constraints considered during the project. Understanding constraints helps in making informed decisions and avoiding costly mistakes.
Context and Scope
Context delimits the system and defines its boundaries, including external systems, users, and interfaces. A domain perspective provides a high-level overview of the system's context. The scope defines what is included and excluded from the system, helping to manage expectations.
Solution Strategy
The solution strategy outlines the approach used to develop the system. It includes decisions made on technology, architecture, patterns, and frameworks. The strategy should align with the project's goals and constraints.
Building Block View
The building block view depicts the system's structural elements, their relationships, and interactions. It captures the source code's physical and logical structures, allowing for an understanding of the system's architecture.
What is a "building block"?
A building block is a self-contained, reusable system component that performs a specific function. It can be a module, library, service, or interface.
Runtime View
The runtime view shows how the system's building blocks interact with each other during runtime. It includes sequence diagrams or similar representations of scenarios that demonstrate the system's dynamic behavior. This view helps users understand how the system functions.
Deployment View
The deployment view describes how the system is deployed in its execution environment, including hardware and software components. It provides an overview of the technical infrastructure needed to run the system.
Crosscutting Concepts
Crosscutting concepts are essential principles or patterns that apply across multiple building blocks and influence their design and implementation, such as security, performance, or scalability. The crosscutting concepts section helps identify and address common concerns across the system.
Architectural Decisions
Architectural Decision Records (ADRs) document the decisions made during the design and development. They explain why specific alternatives were chosen, helping to understand the system's evolution. ADRs also aid in decision-making when making changes or updates to the system.
Quality Requirements
Quality requirements define a system's non-functional properties, such as performance, reliability, or maintainability. The quality tree method is often used to structure and prioritize quality requirements. Quality requirements should be measurable and testable to ensure the system's success.
Risks and Technical Debt
The risk and technical debt section identifies potential risks and their impact on the project. It also includes strategies for mitigating or addressing these risks. Technical debt refers to any shortcuts, compromises, or trade-offs made during development that may require additional time and effort to rectify in the future.
Glossary
A glossary lists key terms throughout the documentation, providing a shared vocabulary for all team members. It helps in avoiding misunderstandings and promotes effective communication. A glossary can be continuously updated throughout the project as new terms are introduced.
4 Alternatives to arc42
While arc42 is a popular and comprehensive template for documenting software architectures, other alternatives are available. The following are four alternatives that you may consider, depending on your team's needs and preferences.
arc42 vs C4 model
The C4 (Context, Container, Component, and Code) model is a lightweight visual notation depicting software architectures. It focuses on a system's static structures rather than its behavior. Unlike arc42, the C4 model does not have predefined sections or templates for requirements, quality attributes, or risks. Instead, it provides a simple yet effective way to represent the system's structural elements and their relationships.
Both arc42 and the C4 model aim to understand a software system's architecture clearly. However, arc42 offers guidance on documenting non-functional requirements, solution strategies, and crosscutting concepts. The C4 model may be a better fit for teams looking for a simple and visual way to communicate their software architecture.
arc42 vs. TOGAF
The Open Group Architecture Framework (TOGAF) is a popular enterprise architecture framework. It offers guidance and best practices for developing, managing, and governing an organization's IT architecture. Unlike arc42, which focuses on the software architecture of a single system, TOGAF takes a broader and more holistic view of an organization's entire IT architecture.
While arc42 primarily targets software engineers and developers, TOGAF suits enterprise architects and IT managers more. It complements arc42 by providing a high-level overview and alignment with an organization's business goals and strategy.
Can arc42 be used with C4 or TOGAF?
Yes, arc42 can be used with the C4 model or TOGAF. Organizations use multiple frameworks and models to document different aspects of their systems. arc42 can document the software architecture, while C4 or TOGAF can provide a higher-level perspective on the overall IT architecture. Organizations can also modify the arc42 template to incorporate elements from other frameworks. For example, they can include TOGAF's architecture principles or the C4 model's system context diagram in the arc42 documentation.
arc42 vs. UML
UML (Unified Modeling Language) is a graphical notation for visualizing, specifying, constructing, and documenting software systems. It provides various diagrams to represent different aspects of a system, such as class diagrams for static structure, sequence diagrams for dynamic behavior, and component diagrams for deployment architecture.
Unlike arc42, which provides a structured template for documenting software architecture, UML is a modeling language with no predefined structure. It allows for more flexibility and customization but requires more effort to create and maintain documentation. Organizations may choose to use arc42 and UML together, with arc42 providing the overall structure and UML diagrams used to illustrate specific aspects of the system.
arc42 vs. Archimate
Archimate is an open standard for modeling and describing enterprise architectures. The language provides concepts and relationships for representing an organization's business, application, and technology layers.
Like UML, Archimate is not a template or framework but a modeling language that can be used in conjunction with arc42. Organizations may use arc42 to document the software architecture and Archimate to model the higher-level enterprise architecture, with cross-links between the two.
Final Thoughts
As you can see, several alternatives to arc42 for documenting software architectures exist. Each has its advantages and may be suitable for different contexts. However, arc42 remains a popular and comprehensive template for teams to document their software systems.
Its flexibility allows for incorporating elements from other models and frameworks, making it a valuable tool for any organization. Contact us if you are looking for expert developers and software architects to help implement your project and document it well.
iRonin provides guidance and support in using arc42 or other alternatives to document your software architecture effectively. Our team has experience building and documenting software systems, and we would be happy to assist you with your project.
