GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — Strengthen Standard Base Documentation from community talk by rrrutledge · Pull Request #908 · InnerSourceCommons/InnerSourcePatterns

Conversation

@rrrutledge

@rrrutledge rrrutledge commented May 20, 2026

Copy link
Copy Markdown
Contributor

Summary

Three structural improvements to the Standard Base Documentation pattern, plus a new Known Instance citation. Informed by Fiji "FJ"'s community talk Docs that Invite Devs (YouTube), which articulates why InnerSource docs frequently fail to convert readers into contributors.

Changes

  • New ARCHITECTURE.md section in the Solution as a contributor-facing system map. Distinct from Document Architecture Decisions (ADRs): ADRs capture decisions over time, whereas ARCHITECTURE.md is a current-state map that lets contributors tell which parts of the system are safe to touch.
  • New "How to know your docs are working" check — a usability acceptance criterion listing the five questions a newcomer should be able to answer from a quick scan: what is this, where do I start, how does it work, where do I contribute, what happens next?
  • Sharper Getting Started guidance in README-template.md: copy-pasteable steps, expected outputs per step, and a troubleshooting subsection. Replaces the previous one-line description.
  • New entry under Known Instances citing the talk, labeled as "Community talk" so it is clearly distinct from the existing organizational adoptions (Europace, Paypal, Mercado Libre, Analog Devices, Airbus, Siemens).

Why now

The talk surfaces real gaps the existing pattern doesn't yet cover — particularly contributor-facing architectural orientation and an explicit usability check. Edits were kept surgical so they extend rather than reframe the pattern.

Test plan

  • Review the rendered base-documentation.md for prose flow and cross-link correctness (the new ARCHITECTURE.md section links to Document Architecture Decisions).
  • Confirm the new "Community talk" Known Instance entry reads correctly alongside the organizational entries.
  • Confirm the README template's revised Getting Started section reads as actionable guidance for newcomers.

🤖 Generated with Claude Code

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@rrrutledge @claude
Strengthen Standard Base Documentation from community talk
6d87f9d 
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) <[email protected]>
@rrrutledge
rrrutledge requested review from NewMexicoKid, cewilliams, lenucksi, robtuley, spier and yuhattor as code owners May 20, 2026 19:13
rrrutledge and others added 2 commits May 20, 2026 14:22
@rrrutledge
Correct speaker attribution in Known Instances
ebc191f 
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.
@spier
Teaching the vale some more words
c40ec58
spier
spier reviewed May 27, 2026
View reviewed changes
Comment thread patterns/2-structured/base-documentation.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).
* **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)).

@spier spier May 27, 2026

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rrrutledge which organization was this approach validated at? I could not find Agentic Systems in connection to the authors name on a quick scan.

If we are not certain enough that this is actually an org that this approach was applied at, we could also add this content to the "References" section.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions

@spier spier Jun 22, 2026

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rrrutledge could you add more context to this?

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
@spier spier added 2-structured Patterns with existing instances (Please see our contribution handbook for details) 📖 Type - Content Work Working on contents is the main focus of this issue / PR labels May 27, 2026
@github-actions github-actions Bot mentioned this pull request Jun 1, 2026
Monthly Metrics: New Issues + New Pull Requests 2026-05-01..2026-05-31 #911
Open
@spier
Merge branch 'main' into enhance-base-documentation-from-talk
e8699a7
@rrrutledge rrrutledge closed this Jul 15, 2026
@spier

spier commented Jul 16, 2026

Copy link
Copy Markdown
Member

@rrrutledge thanks for cleaning up the PRs.

Just curious, what was the reason for not following this idea any more? Missing feedback from the community talk speaker, or similar?
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@spier spier spier left review comments
@lenucksi lenucksi Awaiting requested review from lenucksi lenucksi is a code owner
@NewMexicoKid NewMexicoKid Awaiting requested review from NewMexicoKid NewMexicoKid is a code owner
@cewilliams cewilliams Awaiting requested review from cewilliams cewilliams is a code owner
@robtuley robtuley Awaiting requested review from robtuley robtuley is a code owner
@yuhattor yuhattor Awaiting requested review from yuhattor yuhattor is a code owner

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

2-structured Patterns with existing instances (Please see our contribution handbook for details) 📖 Type - Content Work Working on contents is the main focus of this issue / PR

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

2 participants

@rrrutledge @spier
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.