Skip to content

Strengthen Standard Base Documentation from community talk #908

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rrrutledge wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Strengthen Standard Base Documentation from community talk #908

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6d87f9d
Strengthen Standard Base Documentation from community talk
rrrutledge May 20, 2026
ebc191f
Correct speaker attribution in Known Instances
rrrutledge May 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions patterns/2-structured/base-documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,19 @@

![CONTRIBUTING.md](../../assets/img/standard-base-documentation/CONTRIBUTING-for-contributors.png)

### ARCHITECTURE.md

For projects of non-trivial size, consider providing a separate `ARCHITECTURE.md` document. Where the `README.md` orients *users*, an `ARCHITECTURE.md` orients potential *contributors* so they know where to make a change and what they might break. This is distinct from Architecture Decision Records (see [Document Architecture Decisions](../1-initial/document-architecture-decisions.md)), which capture *decisions over time*; `ARCHITECTURE.md` is a current-state map of the system aimed at making contribution feel safe.

Typically it should cover:

* A high-level overview of the project's main components and the boundaries between them.
* Which module or directory owns which responsibility, and how the modules interact.
* A handful of conventions or invariants a contributor should know before changing code (e.g. "all public APIs live in the `api/` package", "anything in `core/` requires a corresponding test").

Check failure on line 92 in patterns/2-structured/base-documentation.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[ISC.Spelling] Did you really mean 'invariants'?

Raw Output:
{"message": "[ISC.Spelling] Did you really mean 'invariants'?", "location": {"path": "patterns/2-structured/base-documentation.md", "range": {"start": {"line": 92, "column": 31}}}, "severity": "ERROR"}
* A pointer to where deeper design rationale lives, if Architecture Decision Records or design docs exist.

Without this kind of map, would-be contributors often hesitate not because they lack skill, but because they cannot tell which parts of the system are safe to touch.

### COMMUNICATION.md

Create a separate `COMMUNICATION.md` document. Link this document to your `README.md` so comprehensive contact information can be provided and not take up the extra space in your README. This document should answer frequently
Expand Down Expand Up @@ -120,6 +133,18 @@
started right away: [README-template.md](templates/README-template.md),
[CONTRIBUTING-template.md](templates/CONTRIBUTING-template.md), and [COMMUNICATION-template.md](templates/COMMUNICATION-template.md).

### How to know your docs are working

A practical check: a newcomer scanning your project for a few minutes — without asking anyone — should be able to answer these five questions:

1. What is this project?
2. Where do I start as a user?
3. How does it work at a high level?
4. If I want to help, where do I begin?
5. If I make a contribution, what happens next?

If any of these are hard to find from a quick scan of your docs, decide which file should answer it and add a short, prominent entry there. Potential contributors typically scan rather than read end-to-end, and many leave silently when these questions are not quickly answered.

## Resulting Context

* The time for contributors to get up to speed is significantly reduced.
Expand All @@ -134,6 +159,7 @@
* **Analog Devices Inc.**
* **Airbus**
* **Siemens** automatically creates a checklist issue for every new InnerSource project to make maintainers aware of mandatory requirements (e.g. business approval, license & copyright, export control, contributing guidelines, maintainer maturity) as well as best practices (e.g. documentation as code, semantic versioning, continuous integration/deployment).
* **Agentic Systems** - Feyijimi "FJ" Erinle's talk *Docs That Invite Devs* at the InnerSource Commons articulates why InnerSource docs frequently fail to convert readers into contributors and proposes a README / Getting Started / Architecture / CONTRIBUTING blueprint along with a "5 questions in 5 minutes" usability check ([YouTube](https://www.youtube.com/watch?v=ay_ktbK9lhs)).

Check failure on line 162 in patterns/2-structured/base-documentation.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[ISC.Spelling] Did you really mean 'Devs'?

Raw Output:
{"message": "[ISC.Spelling] Did you really mean 'Devs'?", "location": {"path": "patterns/2-structured/base-documentation.md", "range": {"start": {"line": 162, "column": 71}}}, "severity": "ERROR"}

Check failure on line 162 in patterns/2-structured/base-documentation.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[ISC.Spelling] Did you really mean 'Erinle's'?

Raw Output:
{"message": "[ISC.Spelling] Did you really mean 'Erinle's'?", "location": {"path": "patterns/2-structured/base-documentation.md", "range": {"start": {"line": 162, "column": 39}}}, "severity": "ERROR"}

Check failure on line 162 in patterns/2-structured/base-documentation.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[ISC.Spelling] Did you really mean 'Feyijimi'?

Raw Output:
{"message": "[ISC.Spelling] Did you really mean 'Feyijimi'?", "location": {"path": "patterns/2-structured/base-documentation.md", "range": {"start": {"line": 162, "column": 25}}}, "severity": "ERROR"}

Check failure on line 162 in patterns/2-structured/base-documentation.md

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[ISC.Spelling] Did you really mean 'Agentic'?

Raw Output:
{"message": "[ISC.Spelling] Did you really mean 'Agentic'?", "location": {"path": "patterns/2-structured/base-documentation.md", "range": {"start": {"line": 162, "column": 5}}}, "severity": "ERROR"}

## Authors

Expand Down
10 changes: 7 additions & 3 deletions patterns/2-structured/templates/README-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,13 @@ See also [mission statement chapter](https://producingoss.com/en/producingoss.ht

## Getting Started

This section should contain brief documentation written for first time users on
how to get started using the project. Further more detailed documentation can be
linked to from here.
This section should get first-time users running in minutes. To reduce friction:

* Make setup steps copy-pasteable. A reader should be able to copy a command and run it without rewriting it.
* State the *expected output* of each step so readers know they are on track.
* Include a short "Common problems" or "Troubleshooting" subsection covering the errors past first-timers have hit, so readers can resolve issues without leaving the documentation.

Further more detailed documentation can be linked to from here.

## Further information

Expand Down
Loading