Content refactoring (#60)

Co-authored-by: Olaf Zimmermann <[email protected]>

.github/workflows/pages-deploy.yml

@@ -1,8 +1,6 @@
 name: "Build and Deploy"
 on:
   push:
-    branches:
-      - main
     paths-ignore:
       - .gitignore
       - README.md

.vscode/extensions.json

@@ -1,3 +1,7 @@
 {
-  "recommendations": ["ms-vscode-remote.remote-containers"]
-}
+  "recommendations": [
+    "davidanson.vscode-markdownlint",
+    "ltex-plus.vscode-ltex-plus",
+    "ms-vscode-remote.remote-containers"
+  ]
+}

CONTRIBUTING.md

@@ -1,3 +1,6 @@
 # Contributing to adr.github.io
 
-To improve this page, head to <https://github.com/adr/adr.github.io>, edit `index.md` or `_tabs/*.md`, and submit a pull request.
+To improve this page, head to <https://github.com/adr/adr.github.io>, edit `_posts/*.md`, and submit a pull request.
+
+See [Chirpy's Text and Typography](https://chirpy.cotes.page/posts/text-and-typography/) post for information on possible styling.
+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

@@ -1,4 +1,4 @@
-# adr.git.hub.io
+# adr.github.io
 
 This is the source code of <https://adr.github.io>.
 It is based on the [Chirpy](https://chirpy.cotes.page/) theme.

_config.yml

@@ -150,7 +150,7 @@ pwa:
     deny_paths:
       # - "/example"  # URLs match `<SITE_URL>/example/*` will not be cached by the PWA
 
-# paginate: 10
+paginate: 10
 
 # The base URL of your site
 baseurl: ""
@@ -171,7 +171,7 @@ kramdown:
 
 collections:
   tabs:
-    output: true
+    output: false
     sort_by: order
 
 defaults:
@@ -184,7 +184,7 @@ defaults:
       toc: true # Display TOC column in posts.
       # DO NOT modify the following parameter unless you are confident enough
       # to update the code of all other post links in this project.
-      permalink: /posts/:title/
+      permalink: :title/
   - scope:
       path: _drafts
     values:

_data/share.yml

@@ -2,48 +2,36 @@
 #  Icons from <https://fontawesome.com/>
 
 platforms:
-  - type: Twitter
-    icon: "fa-brands fa-square-x-twitter"
-    link: "https://twitter.com/intent/tweet?text=TITLE&url=URL"
-
-  - type: Facebook
-    icon: "fab fa-facebook-square"
-    link: "https://www.facebook.com/sharer/sharer.php?title=TITLE&u=URL"
-
-  - type: Telegram
-    icon: "fab fa-telegram"
-    link: "https://t.me/share/url?url=URL&text=TITLE"
-
   # Uncomment below if you need to.
   #
-  # - type: Linkedin
-  #   icon: "fab fa-linkedin"
-  #   link: "https://www.linkedin.com/sharing/share-offsite/?url=URL"
+  - type: Linkedin
+    icon: "fab fa-linkedin"
+    link: "https://www.linkedin.com/sharing/share-offsite/?url=URL"
   #
   # - type: Weibo
   #   icon: "fab fa-weibo"
   #   link: "https://service.weibo.com/share/share.php?title=TITLE&url=URL"
   #
-  # - type: Mastodon
-  #   icon: "fa-brands fa-mastodon"
-  #   # See: https://github.com/justinribeiro/share-to-mastodon#properties
-  #   instances:
-  #     - label: mastodon.social
-  #       link: "https://mastodon.social/"
-  #     - label: mastodon.online
-  #       link: "https://mastodon.online/"
-  #     - label: fosstodon.org
-  #       link: "https://fosstodon.org/"
+  - type: Mastodon
+    icon: "fa-brands fa-mastodon"
+    #   # See: https://github.com/justinribeiro/share-to-mastodon#properties
+    instances:
+      #     - label: mastodon.social
+      #       link: "https://mastodon.social/"
+      #     - label: mastodon.online
+      #       link: "https://mastodon.online/"
+      - label: fosstodon.org
+        link: "https://fosstodon.org/"
   #     - label: photog.social
   #       link: "https://photog.social/"
   #
-  # - type: Bluesky
-  #   icon: "fa-brands fa-bluesky"
-  #   link: "https://bsky.app/intent/compose?text=TITLE%20URL"
+  - type: Bluesky
+    icon: "fa-brands fa-bluesky"
+    link: "https://bsky.app/intent/compose?text=TITLE%20URL"
   #
-  # - type: Reddit
-  #   icon: "fa-brands fa-square-reddit"
-  #   link: "https://www.reddit.com/submit?url=URL&title=TITLE"
+  - type: Reddit
+    icon: "fa-brands fa-square-reddit"
+    link: "https://www.reddit.com/submit?url=URL&title=TITLE"
   #
   # - type: Threads
   #   icon: "fa-brands fa-square-threads"

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

@@ -0,0 +1,58 @@
+---
+title: ADR Templates
+pin: true
+mermaid: true
+toc: true
+categories: [adr]
+---
+
+The following UML class diagram shows that many templates for ADR capturing exist, including (but not limited to) MADR, Nygardian ADRs, and Y-Statements:
+
+```mermaid
+classDiagram
+  direction TB
+  class ADR {
+    <<abstract>>
+  }
+  ADR <|-- MADR
+  ADR <|-- NygardADR
+  ADR <|-- Y-Statement
+  ADR <|-- OtherADRTemplate
+```
+
+### Markdown Architectural Decision Records (MADR)
+
+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).
+
+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.
+
+### Nygard ADR
+
+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." -->
+
+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).
+
+### Y-Statement
+
+In short, the Y-statement is as follows:
+
+> In the context of `<use case/user story u>`, facing `<concern c>` we decided for `<option o>` to achieve `<quality q>`, accepting `<downside d>`.
+
+The long form of it is as follows (extra section "because"):
+
+> In the context of `<use case/user story>`,
+> facing `<concern>`,
+> we decided for `<option>`
+> and neglected `<other options>`,
+> to achieve `<system qualities/desired consequences>`,
+> accepting `<downside/undesired consequences>`,
+> because `<additional rationale>`.
+
+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.
+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).
+
+### Other ADR templates
+
+Numerous other ADR formats exist, many of which are also featured in [@joelparkerhenderson's GitHub repository](https://github.com/joelparkerhenderson/architecture_decision_record).
+
+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

@@ -0,0 +1,41 @@
+---
+title: AD Practices
+toc: true
+categories: [adr]
+---
+
+> The lists on this page point at ADR capturing practices and related advice but do not necessarily endorse all of them.
+{: .prompt-info }
+
+[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.
+
+## AD Making
+
+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.
+
+[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.
+
+## Good ADRs --- and How to Get to Them
+
+### Authored by one or more of the maintainers of `adr.github.io/` and the MADR project/template
+
+1. [Definition of Ready for Architectural Decisions](https://ozimmer.ch/practices/2023/12/01/ADDefinitionOfReady.html), suggesting five criteria abbreviated as START.
+2. [Architectural Significance Test and Some Core Decisions](https://www.ozimmer.ch/practices/2020/09/24/ASRTestECSADecisions.html)
+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.
+4. [The Markdown ADR (MADR) Template Explained and Distilled](https://www.ozimmer.ch/practices/2022/11/22/MADRTemplatePrimer.html)
+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*.
+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).
+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
+8. [An Adoption Model for Architectural Decision Making and Capturing](https://ozimmer.ch/practices/2023/04/21/ADAdoptionModel.html)
+
+Most of the material referenced above is also available on [Medium](https://medium.com/olzzio/tagged/adr).
+
+### Third-party articles
+
+- [Documenting Architecture Decisions](https://www.fabian-keller.de/blog/documenting-architecture-decisions), blog post by Fabian Kleiser
+- More will be featured in future versions of this page, suggestions are welcome!
+- *to be continued*
+
+## From Architectural Decisions to Design/Any Decisions
+
+[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

@@ -0,0 +1,64 @@
+---
+title: Decision Capturing Tools
+toc: true
+categories: [adr]
+---
+
+> The following lists are rather inclusive and sorted alphabetically.
+> Please find out about the status and the maturity of the list entries for yourself by following the links.
+> We are happy to include more candidate assets here.
+{: .prompt-info }
+
+## Tooling to create and maintain decision files
+
+### Any template
+
+- [dotnet-adr](https://github.com/endjin/dotnet-adr) - A cross platform .NET Global Tool for creating and managing Architectural Decision Records (ADR).
+
+### MADR template
+
+| Name                                                                                                        | MADR Version                          | Comment                                                                                                                 |
+| ----------------------------------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| [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                                                                    |
+| [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                                             |
+| [ADR Manager VS Code Extension](https://github.com/adr/vscode-adr-manager)                                  | 2.1.2                                 | Visual Studio Code (VS Code) extension                                                                                  |
+| [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 |
+| [Hugo Markdown ADR Tools](https://github.com/butonic/adr-tools)                                             | 2.1.2.                                | CLI to create and update ADRs                                                                                           |
+| [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.                                            |
+| [pyadr](https://github.com/opinionated-digital-center/pyadr)                                                | 2.1.2                                 | CLI to help with an ADR process lifecycle (proposal/acceptance/rejection/deprecation/superseding)                       |
+
+### Nygard template
+
+- [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).
+  - Ansible script to install adr-tools: [ansible-adr-tools](https://github.com/escalate/ansible-adr-tools)
+  - C# rewrite: [adr-cli](https://github.com/GingerTommy/adr-cli)
+  - Go rewrite: [adr](https://github.com/marouni/adr)
+  - Java rewrite: [adr-j](https://github.com/adoble/adr-j)
+  - ESM Node.js port: [adr-tools](https://github.com/meza/adr-tools)
+  - Node.js rewrite: [adr](https://github.com/phodal/adr)
+  - PHP version: [phpadr](https://github.com/globtec/phpadr)
+  - Powershell module: [adr-ps](https://github.com/rdagumampan/adr-ps)
+  - Python rewrite: [adr-tools-python](https://pypi.org/project/adr-tools-python/)
+  - Another Powershell module: [ArchitectureDecisionRecords](https://github.com/ajoberstar/ArchitectureDecisionRecords)
+  - Rust rewrite: [adrs](https://github.com/joshrotenberg/adrs)
+- [adr-viewer](https://github.com/mrwilson/adr-viewer) - python application to generate a website from a set of ADRs.
+- [architectural-decision](https://github.com/cspray/architectural-decision): PHP library to create ADRs using PHP8 Attributes.
+- [Loqbooq](https://loqbooq.app): Commerical Web App with Slack integration to record ADR-inspired decision logs
+- [Talo](https://github.com/canpolat/talo): CLI (and dotnet tool) to manage and export ADRs, RFCs and custom software design document types.
+
+## Tooling close to the code
+
+- [(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.
+
+## Tooling related to architecture management
+
+- [ArchUnit](https://github.com/TNG/ArchUnit): unit tests for architecture
+- [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.
+- [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/).
+
+## Interesting, but unmaintained tooling
+
+- [adr-log](https://github.com/adr/adr-log): Generates an architectural decision log out of MADRs.
+- [ADMentor](https://github.com/IFS-HSR/ADMentor) Architectural Decision Modeling Add-In for [Sparx Enterprise Architect](https://www.sparxsystems.de/uml/neweditions/)
+- [eadlsync](https://adr.github.io/eadlsync/): Synchronizes embedded architectural decision records with a repository of architectural decisions.
+- [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

@@ -0,0 +1,5 @@
+---
+icon: fas fa-check-circle
+order: 2
+title: AD Practices
+---

_tabs/adr-templates.md

@@ -0,0 +1,5 @@
+---
+icon: fas fa-file-text
+order: 2
+title: ADR Templates
+---

_tabs/adr-tooling.md

@@ -0,0 +1,5 @@
+---
+icon: fas fa-briefcase
+order: 4
+title: Decision Capturing Tools
+---

categories.md

@@ -0,0 +1,5 @@
+---
+layout: categories
+icon: fas fa-stream
+order: 1
+---