In software development, Architecture Decision Records (ADRs) are a proven method for documenting important decisions and making them transparent for everyone. This is especially important when the original decision-makers have long since left the company and the reason for their decision is no longer accessible.
But where and how should you best manage these documents? Many teams already use Redmine as a project management tool – and often don’t realize that the integrated wiki is ideal for managing ADRs.
Why the Redmine Wiki?
- Everything in One Place Redmine is already in use in many project teams. The wiki is directly integrated, so you only need to enable the module in your project to use it. All ADRs are then centrally located in this project wiki and linked with other project information.
- Simple Structure With the Redmine wiki, you can create a separate page for each ADR and link them together. A simple main page with a list of all ADRs is enough to keep track. The structure remains flexible and adapts to your requirements.
- Versioning and History Every change to a wiki page is automatically logged. This way, you can always see who changed what and when – a crucial advantage if you want to understand why a particular decision was made or later adjusted.
- Team Collaboration The Redmine wiki allows all team members to read, comment on, and update ADRs as needed. Through permissions management, you can control who may make changes and who can only read.
Example from Practice
A typical ADR in the Redmine wiki might look like this:
## ADR-001: Why are we using Docker for deployment? * **Status:** Accepted (2025-06-01) * **Context:** We need a flexible, reproducible environment for our microservices. * **Options:** Virtual machines, Docker, Kubernetes * **Decision:** Docker * **Rationale:** Docker provides simple containerization, fast deployment, and good integration with our existing infrastructure. * **Consequences:** The team needs to learn Docker, but in the long run we benefit from the flexibility.
The syntax of the Redmine wiki follows the globally configured text formatting of Redmine (Textile → outdated, CommonMark Markdown (GitHub Flavored) → recommended)
The Redmine wiki is a practical, cost-effective solution for managing ADRs – especially for teams already using Redmine. It offers everything you need for clear, transparent, and collaborative documentation: central storage, versioning, and easy editing.
And for those who need more or value extensive search functions, the Redmine Wiki Guide Plugin offers additional useful features to support you in documenting ADRs.
Additional Features through the Wiki Guide Plugin for Redmine
- With intelligent LiveSearch, you can find content even faster than through the global Redmine search.
- Regex operators in wiki list filters help you pinpoint specific information in content or titles more precisely.
- TAGs for wiki pages ensure clear categorization of ADRs.
- Multi-level approval workflows ensure that only reviewed content is published.
- Read confirmations guarantee that important documents actually reach everyone.
- Automatic lists identify orphaned or outdated pages.
- The wiki list allows filtering by relevant metrics such as author, watchers, confidential, updated, status, etc.
- and much more…
Try it out and bring more transparency to your architecture decisions!
All information about our extensions for Redmine is available on our product page. Customers whose Redmine doesn’t meet the minimum requirements or who prefer to hire someone for the installation and regular maintenance of their Redmine instance have the option to book our Managed Application Hosting for Redmine. Here, the plugin is already part of our hosting offering. The functionality can be extensively tested in our online demo.