From 6d87f9df3894d45b7ea0b6a508705a80b4b3b965 Mon Sep 17 00:00:00 2001 From: Russ Rutledge Date: Wed, 20 May 2026 14:13:23 -0500 Subject: [PATCH 1/2] Strengthen Standard Base Documentation from community talk Adds three structural improvements to the Standard Base Documentation pattern, informed by Fiji "FJ"'s talk "Docs that Invite Devs": - New ARCHITECTURE.md section as a contributor-facing system map, distinct from Document Architecture Decisions (ADRs). Addresses the contributor hesitation of not knowing what is safe to touch. - New "How to know your docs are working" check, listing the five questions a newcomer should be able to answer from a quick scan. - Sharper Getting Started guidance in the README template: copy-pasteable steps, expected outputs, and a troubleshooting subsection. Also adds the talk under Known Instances, labeled as a community talk to distinguish it from the existing organizational adoptions. Co-Authored-By: Claude Opus 4.7 (1M context) --- patterns/2-structured/base-documentation.md | 26 +++++++++++++++++++ .../2-structured/templates/README-template.md | 10 ++++--- 2 files changed, 33 insertions(+), 3 deletions(-) diff --git a/patterns/2-structured/base-documentation.md b/patterns/2-structured/base-documentation.md index 9004df865..53ae43952 100644 --- a/patterns/2-structured/base-documentation.md +++ b/patterns/2-structured/base-documentation.md @@ -81,6 +81,19 @@ topics: ![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"). +* 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 @@ -120,6 +133,18 @@ In addition to that, this pattern comes with three very basic templates to get y 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. @@ -134,6 +159,7 @@ started right away: [README-template.md](templates/README-template.md), * **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). +* **Community talk** - Fiji "FJ", *Docs that Invite Devs*, 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)). ## Authors diff --git a/patterns/2-structured/templates/README-template.md b/patterns/2-structured/templates/README-template.md index 07fe0def2..fb90a1183 100644 --- a/patterns/2-structured/templates/README-template.md +++ b/patterns/2-structured/templates/README-template.md @@ -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 From ebc191ffe33d8337b6d3b731941edf38a77e5f99 Mon Sep 17 00:00:00 2001 From: Russ Rutledge Date: Wed, 20 May 2026 14:22:21 -0500 Subject: [PATCH 2/2] Correct speaker attribution in Known Instances Replace placeholder "Community talk" entry with the speaker's full name (Feyijimi "FJ" Erinle) and organization (Agentic Systems), matching the format of the existing organizational Known Instances. Speaker affiliation was obtained from the YouTube video description. --- patterns/2-structured/base-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/patterns/2-structured/base-documentation.md b/patterns/2-structured/base-documentation.md index 53ae43952..2288e0c74 100644 --- a/patterns/2-structured/base-documentation.md +++ b/patterns/2-structured/base-documentation.md @@ -159,7 +159,7 @@ If any of these are hard to find from a quick scan of your docs, decide which fi * **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). -* **Community talk** - Fiji "FJ", *Docs that Invite Devs*, 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)). +* **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)). ## Authors