Contribute

You can send us a documentation to publish here, or a link to one.

What you have	Where it goes
Complete, and republishable here	An example directory , the rest of this page
Complete, but not republishable	A link under In the Wild
A fragment of a single section	docs.arc42.org

Contribute an example

An example is one directory. Adding one is simple: no navigation file to edit, no index to update, no configuration to touch.

What we are looking for

• A (fairly) complete arc42 documentation: most of the sections used, even where a section only says "not documented in the original".
• A real system. Anonymised is fine.
• Clear provenance: who wrote it, under what licence, and permission to republish it here. Without that information, we cannot merge your pull request!

How

1. Fork the repository.
2. make new-system SLUG=your-system: this copies _systems/_TEMPLATE/ and fixes the one line that names the directory.
3. Fill in index.md first. Its front matter is the dashboard tile.
4. Write the twelve sections. Images go in your directory's images/; anything you converted from (AsciiDoc, PlantUML, drawio) goes in _originals/, which is kept for provenance and never published.
5. make dev, look at it, then open a pull request.

Markdown is canonical

Whatever the documentation was written in, the Markdown in this repository becomes the source of truth once it is merged. Examples are snapshots and are not synchronised with their originals, so there is nothing to round-trip. That is why the site needs no conversion step at build time and runs on plain GitHub Pages.

House rules for the writing

• Keep the arc42 section titles. Readers navigate by them.
• Say when something is missing rather than deleting the section. An honest gap is useful to someone comparing examples.

Documentation we cannot host

Plenty of good arc42 documentation cannot be republished here: Their licence does not allow it, or it belongs on the site it already lives on. We link to it from In the Wild instead.

That page is a reading list! Nothing on it has been read end to end by us.

How

Add one entry to _data/in-the-wild.yml and open a pull request. Nothing else changes — there is no page to edit and no navigation to update.

- title:       Name of the documentation
  url:         https://example.org/arch/
  author:      Who wrote it
  description: One neutral sentence — what the system is.
  added:       2026-08
  language:    German          # omit when it is English
  year:        2019            # if knowable

Leave out the note field. That one sentence is our editorial voice: What is worth looking at. We write it ourselves after looking at your link.

Keep description factual and free of praise: what the system does, for whom, at roughly what size. One sentence.

</div> </div>