mirror of
https://github.com/priyanshujain/margin.git
synced 2026-10-04 03:57:03 +00:00
75 lines
3.5 KiB
Markdown
75 lines
3.5 KiB
Markdown
# Prose and docs
|
||
|
||
Applies to everything written: documentation, code comments, app copy, commit messages, PR bodies,
|
||
App Store text, website copy and replies in chat.
|
||
|
||
## Never use an em dash or an en dash
|
||
|
||
Not `—`, not `–`, anywhere. Use a comma, a colon, a semicolon, brackets, or a full stop and a new
|
||
sentence. Pick the one that fits the sentence: swapping the character mechanically produces comma
|
||
splices and broken headings.
|
||
|
||
When editing existing copy, sweep for both characters and replace them.
|
||
|
||
## Never draw a directory tree
|
||
|
||
Not in a README, not in a doc, not in a comment, not in a chat reply. A tree is stale the day
|
||
somebody adds a file, and anyone who wants the layout can look at it. Name the specific path that
|
||
matters, `docs/setup.md`, and move on.
|
||
|
||
## READMEs
|
||
|
||
A README is the project description and nothing else. Under 15 lines: what the project is, what it
|
||
does, links to the docs.
|
||
|
||
Setup, usage, internals and design each get their own file in `docs/`. No features list restating
|
||
the description, no emoji headings, no badges, no contributing boilerplate.
|
||
|
||
A long, exhaustive, everything-on-one-page README is the clearest tell of AI-generated code. People
|
||
are happy to use AI. They do not want their repo to look like it.
|
||
|
||
## The docs set
|
||
|
||
Margin Calendar settled the shape and the other apps followed it. A Margin app's `docs/` holds
|
||
`architecture.md`, `conventions.md`, `design.md`, `setup.md` and `release.md`, plus whatever the
|
||
product needs (`features.md`, `keyboard.md`, `settings.md`, `mobile.md`, `publishing.md`).
|
||
|
||
Put detail where someone would go looking for it, not in the first file they open.
|
||
|
||
Never prefix file names with numbers. `docs/setup.md`, not `docs/01-setup.md`.
|
||
|
||
## Voice
|
||
|
||
Prose a colleague would write. Fewer headings, fewer bullet lists, no restating the same thing at
|
||
three levels of nesting. No padding and no reassurance.
|
||
|
||
## App copy
|
||
|
||
Copy never names a platform. Not "macOS", not "Windows". These ship on Linux and phones too, and a
|
||
message that names one OS is wrong on the others. Say "System Settings" or "the system asks once".
|
||
|
||
Copy never carries a third-party mark or logo. No Google button, no provider logos. The design
|
||
language has no room for someone else's brand.
|
||
|
||
## App Store review notes
|
||
|
||
The reviewer has the built app and nothing else. Never cite a source file, a line number or a repo
|
||
path. Describe what a reviewer can see and do: the UI path to the feature, what it does, the
|
||
observable constraints (bound to loopback only, times out, off until an account is connected).
|
||
|
||
The apps being source-available does not help, because nothing in the notes points at the repo. A
|
||
path is noise in a field with a 4000 character limit.
|
||
|
||
## The checker
|
||
|
||
`scripts/docs-check.mjs` in Margin Mail enforces the dash rule, the no-trees rule and dead links.
|
||
It exists in exactly one repo, and Margin Calendar and Margin Mail are clean while the other two are
|
||
not. Margin's remaining offences, checked on 2026-09-06, are seven dashes in `website/README.md` and
|
||
three source files that put one in user-visible copy: `src/components/Library.tsx`,
|
||
`src/components/ExportPreview.tsx` and `src/export/run.ts`.
|
||
|
||
Note that the checker only reads `.md`, which is exactly why those three went unnoticed. The plan in
|
||
[../naming.md](../naming.md) moves it into the shared toolchain, teaches it to read source files,
|
||
fixes its link regex firing inside inline code spans, and gives it a skip list so Margin Docs'
|
||
markdown test fixtures do not count against it. Until then, sweep by hand.
|