Skip to content

Commit 13397a1

Browse files
kopporOlaf Zimmermann
koppor
and
Olaf Zimmermann
authored
Content refactoring (#60)
Co-authored-by: Olaf Zimmermann <[email protected]>
1 parent e6566ac commit 13397a1

File tree

14 files changed

+234
-166
lines changed

14 files changed

+234
-166
lines changed

‎.github/workflows/pages-deploy.yml‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
11
name: "Build and Deploy"
22
on:
33
push:
4-
branches:
5-
- main
64
paths-ignore:
75
- .gitignore
86
- README.md

‎.vscode/extensions.json‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
11
{
2-
"recommendations": ["ms-vscode-remote.remote-containers"]
3-
}
2+
"recommendations": [
3+
"davidanson.vscode-markdownlint",
4+
"ltex-plus.vscode-ltex-plus",
5+
"ms-vscode-remote.remote-containers"
6+
]
7+
}

‎CONTRIBUTING.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
11
# Contributing to adr.github.io
22

3-
To improve this page, head to <https://github.com/adr/adr.github.io>, edit `index.md` or `_tabs/*.md`, and submit a pull request.
3+
To improve this page, head to <https://github.com/adr/adr.github.io>, edit `_posts/*.md`, and submit a pull request.
4+
5+
See [Chirpy's Text and Typography](https://chirpy.cotes.page/posts/text-and-typography/) post for information on possible styling.
6+
The [source](https://github.com/cotes2020/jekyll-theme-chirpy/blob/master/_posts/2019-08-08-text-and-typography.md?plain=1) shows the respective Markdown source.

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# adr.git.hub.io
1+
# adr.github.io
22

33
This is the source code of <https://adr.github.io>.
44
It is based on the [Chirpy](https://chirpy.cotes.page/) theme.

‎_config.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -150,7 +150,7 @@ pwa:
150150
deny_paths:
151151
# - "/example" # URLs match `<SITE_URL>/example/*` will not be cached by the PWA
152152

153-
# paginate: 10
153+
paginate: 10
154154

155155
# The base URL of your site
156156
baseurl: ""
@@ -171,7 +171,7 @@ kramdown:
171171

172172
collections:
173173
tabs:
174-
output: true
174+
output: false
175175
sort_by: order
176176

177177
defaults:
@@ -184,7 +184,7 @@ defaults:
184184
toc: true # Display TOC column in posts.
185185
# DO NOT modify the following parameter unless you are confident enough
186186
# to update the code of all other post links in this project.
187-
permalink: /posts/:title/
187+
permalink: :title/
188188
- scope:
189189
path: _drafts
190190
values:

‎_data/share.yml‎

Lines changed: 19 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -2,48 +2,36 @@
22
# Icons from <https://fontawesome.com/>
33

44
platforms:
5-
- type: Twitter
6-
icon: "fa-brands fa-square-x-twitter"
7-
link: "https://twitter.com/intent/tweet?text=TITLE&url=URL"
8-
9-
- type: Facebook
10-
icon: "fab fa-facebook-square"
11-
link: "https://www.facebook.com/sharer/sharer.php?title=TITLE&u=URL"
12-
13-
- type: Telegram
14-
icon: "fab fa-telegram"
15-
link: "https://t.me/share/url?url=URL&text=TITLE"
16-
175
# Uncomment below if you need to.
186
#
19-
# - type: Linkedin
20-
# icon: "fab fa-linkedin"
21-
# link: "https://www.linkedin.com/sharing/share-offsite/?url=URL"
7+
- type: Linkedin
8+
icon: "fab fa-linkedin"
9+
link: "https://www.linkedin.com/sharing/share-offsite/?url=URL"
2210
#
2311
# - type: Weibo
2412
# icon: "fab fa-weibo"
2513
# link: "https://service.weibo.com/share/share.php?title=TITLE&url=URL"
2614
#
27-
# - type: Mastodon
28-
# icon: "fa-brands fa-mastodon"
29-
# # See: https://github.com/justinribeiro/share-to-mastodon#properties
30-
# instances:
31-
# - label: mastodon.social
32-
# link: "https://mastodon.social/"
33-
# - label: mastodon.online
34-
# link: "https://mastodon.online/"
35-
# - label: fosstodon.org
36-
# link: "https://fosstodon.org/"
15+
- type: Mastodon
16+
icon: "fa-brands fa-mastodon"
17+
# # See: https://github.com/justinribeiro/share-to-mastodon#properties
18+
instances:
19+
# - label: mastodon.social
20+
# link: "https://mastodon.social/"
21+
# - label: mastodon.online
22+
# link: "https://mastodon.online/"
23+
- label: fosstodon.org
24+
link: "https://fosstodon.org/"
3725
# - label: photog.social
3826
# link: "https://photog.social/"
3927
#
40-
# - type: Bluesky
41-
# icon: "fa-brands fa-bluesky"
42-
# link: "https://bsky.app/intent/compose?text=TITLE%20URL"
28+
- type: Bluesky
29+
icon: "fa-brands fa-bluesky"
30+
link: "https://bsky.app/intent/compose?text=TITLE%20URL"
4331
#
44-
# - type: Reddit
45-
# icon: "fa-brands fa-square-reddit"
46-
# link: "https://www.reddit.com/submit?url=URL&title=TITLE"
32+
- type: Reddit
33+
icon: "fa-brands fa-square-reddit"
34+
link: "https://www.reddit.com/submit?url=URL&title=TITLE"
4735
#
4836
# - type: Threads
4937
# icon: "fa-brands fa-square-threads"

‎_posts/2024-10-25-adr-templates.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
title: ADR Templates
3+
pin: true
4+
mermaid: true
5+
toc: true
6+
categories: [adr]
7+
---
8+
9+
The following UML class diagram shows that many templates for ADR capturing exist, including (but not limited to) MADR, Nygardian ADRs, and Y-Statements:
10+
11+
```mermaid
12+
classDiagram
13+
direction TB
14+
class ADR {
15+
<<abstract>>
16+
}
17+
ADR <|-- MADR
18+
ADR <|-- NygardADR
19+
ADR <|-- Y-Statement
20+
ADR <|-- OtherADRTemplate
21+
```
22+
23+
### Markdown Architectural Decision Records (MADR)
24+
25+
MADR is about architectural decisions that *matter* ([`[ˈmæɾɚ]`](https://en.wiktionary.org/wiki/matter#Pronunciation)). The project provides a [full](https://github.com/adr/madr/blob/4.0.0/template/adr-template.md?plain=1) and a [minimal](https://github.com/adr/madr/blob/4.0.0/template/adr-template-minimal.md?plain=1) template, both of which now come in an annotated and a bare format. Rationale for this decision is available [here](https://github.com/adr/madr/tree/4.0.0/template#decisions).
26+
27+
We think that the *considered options* with their pros and cons are crucial to understand the reasons for choosing a particular design. Therefore, the [Markdown Architectural Decision Records (MADR)](https://adr.github.io/madr/) project in this organization includes such tradeoff analysis information. It also suggests metadata such as decision makers and confirmation in addition to decision status.
28+
29+
### Nygard ADR
30+
31+
An ADR consists of title, status, context, decision, and consequences according to "Documenting Architecture Decisions" by [@mtnygard](https://github.com/mtnygard). <!-- From the Nygard post: "Context This section describes the forces at play, including technological, political, social, and project local." and "We should use a lightweight text formatting language like Markdown or Textile." -->
32+
33+
The blog post from 2011 that suggests this structure is [here](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) and a Markdown rendering of it is available [here](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/locales/en/templates/decision-record-template-by-michael-nygard/index.md).
34+
35+
### Y-Statement
36+
37+
In short, the Y-statement is as follows:
38+
39+
> In the context of `<use case/user story u>`, facing `<concern c>` we decided for `<option o>` to achieve `<quality q>`, accepting `<downside d>`.
40+
41+
The long form of it is as follows (extra section "because"):
42+
43+
> In the context of `<use case/user story>`,
44+
> facing `<concern>`,
45+
> we decided for `<option>`
46+
> and neglected `<other options>`,
47+
> to achieve `<system qualities/desired consequences>`,
48+
> accepting `<downside/undesired consequences>`,
49+
> because `<additional rationale>`.
50+
51+
cards42 has adopted the Y-statement template in its German [ADR card](https://cards42.org#adr); the English version is similar, but adds state information.
52+
Finally, you can find more explanations and examples on Medium: [Y-Statements - A Light Template for Architectural Decision Capturing](https://medium.com/@docsoc/y-statements-10eb07b5a177).
53+
54+
### Other ADR templates
55+
56+
Numerous other ADR formats exist, many of which are also featured in [@joelparkerhenderson's GitHub repository](https://github.com/joelparkerhenderson/architecture_decision_record).
57+
58+
The [template](http://www.iso-architecture.org/42010/templates/) for [ISO/IEC/IEEE 42010:2011](https://en.wikipedia.org/wiki/ISO/IEC_42010), the international standard for architecture descriptions of systems and software emgineering, suggests nine information items for ADRs its Appendix A. It also identifies areas to consider when identifying key decisions.

‎_posts/2024-10-27-ad-practices.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: AD Practices
3+
toc: true
4+
categories: [adr]
5+
---
6+
7+
> The lists on this page point at ADR capturing practices and related advice but do not necessarily endorse all of them.
8+
{: .prompt-info }
9+
10+
[Timing Architectural Decisions](https://ozimmer.ch/assets/presos/ZIO-ITARCKeynoteTADv101p.pdf), a presentation given at the annual Swedish IT architect conference ITARC features many of the practices collected on this page.
11+
12+
## AD Making
13+
14+
The [Design Practice Repository](https://socadk.github.io/design-practice-repository/) on GitHub and the [Design Practice Reference](https://leanpub.com/dpr), a corresponding LeanPub e-Book, feature an AD making and capturing activity, which is positioned as one of the essential activities in DPR.
15+
16+
[Decision-making ADRs: weightings are a work-around](https://jacquiread.com/posts/2024-09-11-decision-making-adrs-weightings-are-a-workaround/) is a blog post by Jacqui Read that offers some tips on how to make better architectural decisions.
17+
18+
## Good ADRs --- and How to Get to Them
19+
20+
### Authored by one or more of the maintainers of `adr.github.io/` and the MADR project/template
21+
22+
1. [Definition of Ready for Architectural Decisions](https://ozimmer.ch/practices/2023/12/01/ADDefinitionOfReady.html), suggesting five criteria abbreviated as START.
23+
2. [Architectural Significance Test and Some Core Decisions](https://www.ozimmer.ch/practices/2020/09/24/ASRTestECSADecisions.html)
24+
3. [How to create ADRs — and how not to](https://www.ozimmer.ch/practices/2023/04/03/ADRCreation.html) collects good practices and anti-patterns.
25+
4. [The Markdown ADR (MADR) Template Explained and Distilled](https://www.ozimmer.ch/practices/2022/11/22/MADRTemplatePrimer.html)
26+
5. [A Definition of Done for Architectural Decision Making](https://www.ozimmer.ch/practices/2020/05/22/ADDefinitionOfDone.html) proposes five criteria and a checklist to decide when it is time to set the status of a single decision to "done": evidence, criteria and alternatives, agreement, documentation, and realization/review plan. Here, we focus on the 'D' in *ecADR*.
27+
6. Context, background and examples of good and bad justifications can be found in [this blog post](https://www.ozimmer.ch/practices/2020/04/27/ArchitectureDecisionMaking.html).
28+
7. [How to review ADRs — and how not to](https://www.ozimmer.ch/practices/2023/04/05/ADRReview.html) has good practices, anti-patterns, review check list
29+
8. [An Adoption Model for Architectural Decision Making and Capturing](https://ozimmer.ch/practices/2023/04/21/ADAdoptionModel.html)
30+
31+
Most of the material referenced above is also available on [Medium](https://medium.com/olzzio/tagged/adr).
32+
33+
### Third-party articles
34+
35+
- [Documenting Architecture Decisions](https://www.fabian-keller.de/blog/documenting-architecture-decisions), blog post by Fabian Kleiser
36+
- More will be featured in future versions of this page, suggestions are welcome!
37+
- *to be continued*
38+
39+
## From Architectural Decisions to Design/Any Decisions
40+
41+
[From Architectural Decisions to Design Decisions](https://medium.com/olzzio/from-architectural-decisions-to-design-decisions-f05f6d57032b) and [ADR = Any Decision Record?](https://medium.com/olzzio/adr-any-decision-record-916d1b64b28d) are two blog posts proposing to extend the scope of ADRs.

‎_posts/2024-10-28-adr-tooling.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
title: Decision Capturing Tools
3+
toc: true
4+
categories: [adr]
5+
---
6+
7+
> The following lists are rather inclusive and sorted alphabetically.
8+
> Please find out about the status and the maturity of the list entries for yourself by following the links.
9+
> We are happy to include more candidate assets here.
10+
{: .prompt-info }
11+
12+
## Tooling to create and maintain decision files
13+
14+
### Any template
15+
16+
- [dotnet-adr](https://github.com/endjin/dotnet-adr) - A cross platform .NET Global Tool for creating and managing Architectural Decision Records (ADR).
17+
18+
### MADR template
19+
20+
| Name | MADR Version | Comment |
21+
| ----------------------------------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
22+
| [adr-log](https://github.com/adr/adr-log?tab=readme-ov-file#adr-log-) | 2.1.2 | CLI to keep an `index.md` file updated with all ADRs |
23+
| [ADR Manager](https://adr.github.io/adr-manager/) | 2.1.2 | Web-based UI connecting to GitHub to directly edit ADRs in a form-based way |
24+
| [ADR Manager VS Code Extension](https://github.com/adr/vscode-adr-manager) | 2.1.2 | Visual Studio Code (VS Code) extension |
25+
| [Backstage ADR plugin](https://github.com/backstage/community-plugins/tree/main/workspaces/adr/plugins/adr) | 2.1.2 and 3.x | plugin to explore and search ADRs within a backstage based developer portal. Search at scale across mutliple orgs/repos |
26+
| [Hugo Markdown ADR Tools](https://github.com/butonic/adr-tools) | 2.1.2. | CLI to create and update ADRs |
27+
| [Log4brains](https://github.com/thomvaill/log4brains) | 2.1.2 without numbers in the filename | Supports both nice rendering of ADRs and creation of ADRs in a command line. |
28+
| [pyadr](https://github.com/opinionated-digital-center/pyadr) | 2.1.2 | CLI to help with an ADR process lifecycle (proposal/acceptance/rejection/deprecation/superseding) |
29+
30+
### Nygard template
31+
32+
- [adr-tools](https://github.com/npryce/adr-tools) - bash scripts to manage ADRs in the [Nygard format](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html). [example](https://github.com/npryce/adr-tools/blob/master/doc/adr/0002-implement-as-shell-scripts.md).
33+
- Ansible script to install adr-tools: [ansible-adr-tools](https://github.com/escalate/ansible-adr-tools)
34+
- C# rewrite: [adr-cli](https://github.com/GingerTommy/adr-cli)
35+
- Go rewrite: [adr](https://github.com/marouni/adr)
36+
- Java rewrite: [adr-j](https://github.com/adoble/adr-j)
37+
- ESM Node.js port: [adr-tools](https://github.com/meza/adr-tools)
38+
- Node.js rewrite: [adr](https://github.com/phodal/adr)
39+
- PHP version: [phpadr](https://github.com/globtec/phpadr)
40+
- Powershell module: [adr-ps](https://github.com/rdagumampan/adr-ps)
41+
- Python rewrite: [adr-tools-python](https://pypi.org/project/adr-tools-python/)
42+
- Another Powershell module: [ArchitectureDecisionRecords](https://github.com/ajoberstar/ArchitectureDecisionRecords)
43+
- Rust rewrite: [adrs](https://github.com/joshrotenberg/adrs)
44+
- [adr-viewer](https://github.com/mrwilson/adr-viewer) - python application to generate a website from a set of ADRs.
45+
- [architectural-decision](https://github.com/cspray/architectural-decision): PHP library to create ADRs using PHP8 Attributes.
46+
- [Loqbooq](https://loqbooq.app): Commerical Web App with Slack integration to record ADR-inspired decision logs
47+
- [Talo](https://github.com/canpolat/talo): CLI (and dotnet tool) to manage and export ADRs, RFCs and custom software design document types.
48+
49+
## Tooling close to the code
50+
51+
- [(Java) Embedded Architectural Decision Records](https://github.com/adr/e-adr#embedded-architectural-decision-records), which shows how a distributed AD log can be embedded in Java Code via ADR annotations.
52+
53+
## Tooling related to architecture management
54+
55+
- [ArchUnit](https://github.com/TNG/ArchUnit): unit tests for architecture
56+
- [docToolchain](https://doctoolchain.github.io/docToolchain/): docToolchain is an implementation of the [docs-as-code](https://www.writethedocs.org/guide/docs-as-code/) approach for software architecture plus some additional automation.
57+
- [Structurizr](https://www.structurizr.com/): Structurizr is a collection of tooling to help you visualise, document and explore your software architecture using the [C4 model](https://c4model.com/).
58+
59+
## Interesting, but unmaintained tooling
60+
61+
- [adr-log](https://github.com/adr/adr-log): Generates an architectural decision log out of MADRs.
62+
- [ADMentor](https://github.com/IFS-HSR/ADMentor) Architectural Decision Modeling Add-In for [Sparx Enterprise Architect](https://www.sparxsystems.de/uml/neweditions/)
63+
- [eadlsync](https://adr.github.io/eadlsync/): Synchronizes embedded architectural decision records with a repository of architectural decisions.
64+
- [SE Repo](https://github.com/adr/serepo): Software Engineering Repository. A repository for versioning software engineering artifacts, which can be architectural decisions, patterns, and others.

‎_tabs/ad-practices.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
icon: fas fa-check-circle
3+
order: 2
4+
title: AD Practices
5+
---

0 commit comments

Comments
 (0)