Required reading for anyone writing or editing docs in this repo. Modeled on the Next.js docs writing-style guide with adjustments for our community-platform context.
The goal of this guide is consistency — not authorial voice. Every doc should read as if one person wrote all of them. If a rule below conflicts with an existing doc, the doc is wrong; open a PR to fix it.
- ✅ "Run
npm installto set up your local environment." - ❌ "The developer should run
npm installto set up their local environment." - ❌ "
npm installwill set up the local environment."
Second-person (you/your) is the default. Use first-person plural (we/our) only when describing project policy or community decisions (e.g., "We enforce DCO sign-off on every commit").
- ✅ "Cursor Boston is a community platform for Boston-area developers using AI-assisted workflows."
- ❌ "Cursor Boston is the premier community platform for Boston-area developers leveraging cutting-edge AI-assisted workflows."
Adjective inflation is the most common quality drop in docs as a project scales. Strip the word and re-read; if the sentence is weaker, keep the word — usually it isn't.
- ✅ "Open
lib/api-schemas/community.tsand add the new route." - ❌ "You'll want to open
lib/api-schemas/community.ts..."
These are banned because they either (a) mislead (calling something "easy" when it isn't is condescending to the reader who's stuck) or (b) waste words.
| Don't | Use instead |
|---|---|
| easy / easily | (drop the word, or be specific: "Takes about 5 minutes") |
| just / simply | (drop the word) |
| obviously | (drop the word) |
| basically | (drop the word) |
| in order to | "to" |
| at this point in time | "now" |
| due to the fact that | "because" |
| utilize | "use" |
| leverage (as a verb) | "use" |
| robust / cutting-edge / world-class | (be specific: "X passes Y test", "X measured at Z") |
| please | (drop in instructions: "Run X" not "Please run X") |
| we recommend | "Do X" or "Prefer X" — be direct |
| should | (use only for genuine choice; otherwise "must") |
Exception: in error messages and Code-of-Conduct-adjacent prose, courtesy words like "please" stay. Banned only in instructions.
These names are not interchangeable.
| Term | Meaning |
|---|---|
| Cursor | The editor product made by Anthropic-adjacent Cursor company at cursor.com. |
| Cursor Boston | This community / this platform. Capitalize both words. |
| the platform | Synonym for Cursor Boston (use sparingly to avoid repetition). |
| the project | Synonym for the codebase + community when context is clear. |
| CB | ❌ Don't abbreviate. |
| the site | The deployed web product at cursorboston.com. |
| the repo | The Git repository at github.com/rogerSuperBuilderAlpha/cursor-boston. |
Subsystem names follow the canonical doc:
| Subsystem | Canonical spelling | Doc |
|---|---|---|
| The game | Generals (proper noun, capitalized) | docs/generals/ |
| Weekly cohort | Summer Cohort | .github/ACTIVE_ISSUES.md |
| Hackathon submissions | PyData submissions, Hack-a-Sprint submissions | per event |
Every new doc declares its Diátaxis quadrant at the top. Pick one — docs that mix quadrants without internal separation produce drift.
- First-person plural ("we'll build…") is OK because the reader and writer are walking the same path.
- Every step has a verifiable outcome (a screenshot, a command output, a passing test).
- Open with "What you'll build" and "What you'll learn".
- Don't reference advanced concepts until they're needed.
- Example:
docs/GET_STARTED.md,docs/FIRST_CONTRIBUTION.md.
- Single goal per doc — name it in the title ("How to publish a hackathon", not "Hackathons").
- Bullet steps, not narrative.
- Assume reader competence — don't re-teach setup if they've reached this doc.
- Close with a "Next steps" pointer.
- Example:
docs/RELEASING.md,docs/HACK_A_SPRINT_2026_OPS.md.
- No prose between entries — tables, lists, code signatures.
- Alphabetize or group by structural similarity (e.g.,
docs/API.mdis grouped by area, alphabetical within). - Mark provenance — say "auto-generated" if it is.
- Example:
docs/API.md,docs/DEVELOPMENT.mdreference sections.
- Narrative is allowed (this is the only quadrant where it is).
- Open with the question the doc answers.
- Cross-link to ADRs / RFCs / specs liberally.
- Example:
docs/adr/,docs/security-incident-2026-04-11.md.
- Single
#(H1) per file, at the top, matching the file's purpose. - Nest
##,###,####cleanly. No skipped levels. - Sentence case for headings: "How to publish a hackathon", not "How To Publish A Hackathon".
- Always specify a language fence:
bashfor shell commands.ts/tsxfor TypeScript (nottypescript).js/jsxfor JavaScript.yamlfor YAML.jsonfor JSON.- Use
```with no language for output / pasted logs / ASCII diagrams.
- One-liner commands use inline backticks (
`npm run dev`), not a code fence. - Don't include the
$prompt in shell blocks. The reader knows.
- Use descriptive link text, not "click here" or bare URLs:
- ✅ "See the release runbook for details."
- ❌ "See this doc for details."
- ❌ "See https://github.com/.../RELEASING.md for details."
- Cross-repo or external URLs: use full URL; don't shorten.
- Same-repo links: use relative paths from the linking file (
../README.mdfrom insidedocs/). - When linking to a section, use the GitHub-rendered slug:
[CONTRIBUTING.md#branching-model-develop-and-main](.github/CONTRIBUTING.md#branching-model-develop-and-main).
- Use
-for unordered lists, not*or+. - Use
1.for ordered lists; let Markdown re-number (write every line as1.). - One-line items don't need terminal punctuation; multi-line items use full sentences.
- Right-align numbers, left-align text.
- One word per cell when possible; multi-word entries indicate a row should split or move to prose.
- Include a header row.
GitHub renders > **Note:** and > **Warning:** blocks well. Use sparingly.
> **Note:** Firestore rules are deployed automatically on push to `main`.
> Don't `firebase deploy` them by hand.
Top-of-file frontmatter is required only for reviews (docs/OPENSOURCE_REVIEW.md, docs/DOCUMENTATION_REVIEW.md) where review_date, commit_sha, previous_review matter. Most docs don't need it.
- Top-level governance / community docs:
UPPERCASE.md(e.g.,README.md,CONTRIBUTING.md,MAINTAINERS.md). - Reference / how-to docs in
docs/:UPPERCASE_WITH_UNDERSCORES.md(e.g.,docs/DEVELOPMENT.md,docs/RELEASING.md). - Tutorial / explanation docs in
docs/:kebab-case.mdonce the Phase 5.3.2 Diátaxis-folder restructure lands. - ADRs:
NNNN-kebab-case-title.md.
- Don't reference future work in instructions. "Once Sentry is shipped, errors will land in Sentry" — fine in explanation; not in a how-to ("To debug errors, check Sentry" is wrong until Sentry exists).
- Don't link to private channels. Discord links are fine (public invite); Slack links are not.
- Don't embed secrets, even fake ones. Use
your-api-key-hereas the placeholder, notsk-1234567890abcdef. - Don't AI-narrate. Don't write "Here's a doc about X" — start the doc.
- Don't write commit messages or PR descriptions as docs. They belong in commit/PR metadata, not in the repo's permanent doc surface.
- Don't add a
Last updated: …line manually. Git tracks this. The one exception: long-cycle policy docs (DESIGN.md, DCO.md) where stakeholders want a visible "last reviewed" date.
When you review someone else's docs PR:
- Does it match its quadrant? If it's labeled how-to but reads like reference, ask for a split.
- Banned words? Search for
easy,just,simply,obviously— usually drop them. - Vocabulary? Cursor vs Cursor Boston used correctly?
- Links work? Use the GitHub PR preview to click through.
- Code blocks have language fences?
- Headings sentence-cased and properly nested?
- Does it duplicate content already in another doc? Link to the canonical home instead of restating.
If you're reviewing your own doc draft, read it aloud — the cadence will tell you when adjective-inflation creeps in.
Update this file by PR like any other doc. Material changes (banned words, vocabulary, file naming) warrant a brief note in the next release CHANGELOG so existing docs can be ratcheted to the new rule.
Last reviewed: 2026-05-18.