Repository navigation
Writing Wiki Pages
This page is the style guide for the OpenBridge wiki. Follow it so every page feels the same and is easy to read, whoever wrote it, person or AI agent.
The wiki is edited in the wiki/ folder of the main repository, not in
the GitHub wiki editor. When a change merges into mainline, a workflow publishes the folder to the
GitHub wiki. Edits made directly on GitHub get overwritten.
- Each page is one file:
wiki/Page-Name.md. The file name is the page name. Use hyphens for spaces, and keep names short and plain ("Record-a-Test-Case", not "Fixture-Authoring"). - Keep every page in the top folder. GitHub wikis flatten folders, so subfolders only cause clashes.
-
Home.mdis the front page,_Sidebar.mdis the menu on every page, and_Footer.mdis the line at the bottom of every page. - Every new page must be added to
_Sidebar.md, in the section where a reader would look for it.
Assume the reader is smart, busy, and new. Many readers are social workers, navigators, legal aid staff, and policy experts, not programmers. Some are people looking for help.
- Plain words at about an 8th grade level. Short sentences. Say "you".
- Explain a term the first time you use it, or link to the Glossary.
- Lead with what the reader can do. Put background after the steps.
- Be honest about the project's status. Never suggest the rules are verified, the app is launched, or results are decisions. They are estimates from draft rules.
- No em dashes and no emoji. Use commas, colons, periods, or parentheses.
- Never include real people's details. Examples use made-up households with round numbers.
Use this shape for most pages:
# Page title
One or two sentences: what this page helps you do, and who it is for.
## Before you start (only if there is something to have ready)
## Steps (numbered, one action per step)
## What happens next (or "Tips", "Common questions")
## Related pages (two to four links)- One
#title per page, then##sections. No deeper than###. - Use numbered lists for steps and bullet lists for options.
- Use a short table when comparing a few things side by side.
- Use a
>quote for one important warning, not for decoration.
| To link to | Write |
|---|---|
| Another wiki page, in a sentence |
[[Glossary]] (see the note below for custom link text) |
| Another wiki page, inside a table |
[the glossary](Glossary) (a pipe would break the table) |
| A file in the repository | [state adapters](https://github.com/Ubiquitouskiwi/OpenBridge/blob/HEAD/docs/STATE_ADAPTERS.md) |
| A folder in the repository | [data folder](https://github.com/Ubiquitouskiwi/OpenBridge/tree/HEAD/data) |
| A website | [211.org](https://www.211.org/) |
To show your own words for a page link in a sentence, put the text first and the page name
after a pipe: [[the glossary|Glossary]]. Do not use that form inside a table.
https://github.com/Ubiquitouskiwi/OpenBridge is filled in with the repository's address when the wiki is published. HEAD means the
default branch.
The wiki explains how to do things. The detailed technical rules stay in the repository: link to
AGENTS.md, docs/, and the
steering files instead of copying them, so there is only one
place to keep up to date.
Use the screenshots in docs/screenshots/. They are made
by a script from the real app with a made-up household, so they stay correct when the app changes.
- Write the text in the square brackets for someone who cannot see the picture: say what it shows, not "screenshot".
- Put a picture right after the step or paragraph it shows. In a numbered list, indent it three spaces so the numbering keeps going.
- Need a picture that does not exist yet? Add it to the script and run
npm run screenshots. The screenshots guide explains how. Never use a picture of a real person's screen or real case details.
Run this from the repository root before opening a pull request:
npm run check:wikiIt reports broken page links, links to repository files or pictures that do not exist, pages
missing from the sidebar, em dashes, and emoji. It also runs as part of npm run verify and in CI.
OpenBridge is a prototype. Its rules are drafts that experts have not verified yet, and results are
estimates, not decisions. It is not legal advice. Need help applying for benefits? Call 211 or visit
211.org. This wiki is edited in the wiki/ folder of the repository.
Questions: openbridge@starlingtek.com.
Start here
Use OpenBridge
- Using OpenBridge
- Understanding your results
- Guide for navigators
- Privacy and your data
- Run it on your computer
- Host it for others
- Use it with an AI assistant
Help without code
- Ways to help
- Review rules as an expert
- Record a test case
- Report a rule problem
- Translate OpenBridge
- Test accessibility
- Community rule toolkit
Rules and policy (with code)
- How the rules engine works
- State adapters
- Add or change a rule
- Add a new state
- Golden test cases
- Yearly data updates
Developers