From 9821d4dcf33d726580928e56b639bb8a34feba70 Mon Sep 17 00:00:00 2001 From: Docs Education Agent Date: Mon, 11 May 2026 00:05:50 -0400 Subject: [PATCH 1/2] Add CONTRIBUTING-docs.md and flesh out README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Publishes the docs contributing bar so community PRs come in pre-shaped. Covers Diataxis mode selection, the quality bar (verified commands, dated freshness lines, real diagrams, no abandoned drafts), the PR submission flow and review expectations, and the project voice. The defect-pattern section cites real findings from the 2026-05-10 docs audit. The README went from one line to a real landing — local-dev commands, where pages live, and a pointer to CONTRIBUTING-docs.md. Co-Authored-By: Paperclip --- CONTRIBUTING-docs.md | 232 +++++++++++++++++++++++++++++++++++++++++++ README.md | 45 ++++++++- 2 files changed, 276 insertions(+), 1 deletion(-) create mode 100644 CONTRIBUTING-docs.md diff --git a/CONTRIBUTING-docs.md b/CONTRIBUTING-docs.md new file mode 100644 index 0000000..a74e3c2 --- /dev/null +++ b/CONTRIBUTING-docs.md @@ -0,0 +1,232 @@ +# Contributing to the ESPresense docs + +Thanks for fixing a doc. The bar is here on purpose — once you know what good looks like, the PR almost writes itself. + +This file covers the docs site at [espresense.com](https://espresense.com), built from this repo. Code/firmware contributions go to [`ESPresense/ESPresense`](https://github.com/ESPresense/ESPresense); the desktop daemon goes to [`ESPresense-companion`](https://github.com/ESPresense/ESPresense-companion). + +--- + +## TL;DR for the impatient + +1. Pick the [Diataxis mode](#1-which-kind-of-page-am-i-writing-diataxis) for what you're writing. One mode per page. +2. If you're documenting firmware behavior or commands, **boot the firmware and run them.** Then add a `Last verified against firmware vX.Y.Z (YYYY-MM-DD)` line. +3. `npm install && npm run dev` to preview at . +4. Open a PR. Maintainer review is usually 1–3 days. Friendly nits are normal; the bar below is what we hold ourselves to too. + +--- + +## 1. Which kind of page am I writing? (Diataxis) + +We use the [Diataxis](https://diataxis.fr/) frame. **Pick one mode per page.** Mixed-mode pages are the single most common reason a docs PR gets sent back. + +| Mode | When to use it | Reader's question | Example on this site | +|---|---|---|---| +| **Tutorial** | Teaching a new user end-to-end the first time | "I just bought an ESP32 — what do I do?" | (in flight) the new Getting Started page | +| **How-to** | Walking an existing user through a specific task | "How do I calibrate my nodes?" | [`guides/calibration.md`](./src/content/docs/guides/calibration.md) | +| **Reference** | Looking up exact options, fields, topics, schemas | "What does `absorption` accept?" | [`configuration/mqtt.md`](./src/content/docs/configuration/mqtt.md), [`configuration/settings.md`](./src/content/docs/configuration/settings.md) | +| **Explanation** | Building the reader's mental model | "Why does Companion need 5–8 nodes per floor and mqtt_room only one?" | [`approach.mdx`](./src/content/docs/approach.mdx) | + +Quick rules of thumb: + +- **Tutorials and how-tos look similar but aren't.** A tutorial assumes nothing and lands somewhere new. A how-to assumes the user already knows what they're trying to do — short, direct, no preamble. +- **Reference is dense and skimmable**, not narrative. Tables, field lists, schemas. If you're writing prose paragraphs in a reference page, you probably want a separate explanation page. +- **Explanation is the only place for "why."** Don't bury the why inside reference tables (we have done this; it's how `companion/configuration.md` ended up at 319 lines doing all four modes at once). +- **If a page wants to be two modes, split it.** Link between them. + +The audit in [ESPA-38](https://github.com/ESPresense/ESPresense/issues) flagged several mixed-mode pages — the patterns to avoid are listed in [The defects we keep finding](#3-the-defects-we-keep-finding) below. + +--- + +## 2. The docs quality bar + +Hold a PR to all six. Maintainers will hold their own PRs to all six. + +### 2.1 Verified commands and config + +If your page contains a command, a YAML/JSON snippet, an MQTT topic, or a UI click-path: + +- **Run it** against the firmware version you're claiming to support, on the kind of board the page targets. Don't paste from memory and don't paste from an old discussion thread without re-running. +- **Use a real value, not a placeholder.** `host: mqtt.local` is verifiable; `host: your_host` teaches nothing and breaks copy-paste. If a placeholder is genuinely necessary, give one full worked example first and then call out which token the reader substitutes. +- **MQTT topics: pick one prefix and stick to it.** The current prefix is `espresense/`. The legacy `room_presence/` prefix appears in old screenshots and stale forum posts; don't reintroduce it. + +### 2.2 Dated freshness line + +Every reference and how-to page gets a one-line freshness footer (or italic line under the title for shorter pages): + +```md +*Last verified against firmware [v4.1.0b0](https://github.com/ESPresense/ESPresense/releases/tag/v4.1.0b0) on 2026-05-10.* +``` + +- Use the actual firmware tag you tested against, with a link to the GitHub release. +- Date in `YYYY-MM-DD`. If you didn't test today, use the date you tested. +- Tutorials: same line, plus the board model you tested on. +- Explanation pages: optional. Date them when the underlying mental model could go stale (e.g. "as of fw v4.x the multilateration solver…"). + +If you can't honestly write this line for a page you're touching, that's a finding — flag it in the PR description and we'll figure it out together. Don't fake the date. + +### 2.3 Real diagrams, not link dumps + +- **Diagrams: SVG with descriptive `alt` text.** JPGs and PNGs are accepted for screenshots only. A "diagram" that's 20 academic PDFs in a bullet list is a link dump, not a diagram (see `guides/technical.md` — that's the cautionary tale). +- **Screenshots: dated and current.** Home Assistant's UI changed "Settings → Apps" to "Settings → Add-ons" — screenshots showing the old labels mislead users. If you're reshooting, drop the file in `public/images/` and reference it with a relative path. +- **Avoid hot-linking** `user-images.githubusercontent.com` URLs. Those break when the user account changes. Commit the image into `public/images/`. + +### 2.4 No abandoned drafts + +- Don't merge a page that's missing the next step. Either finish it or open it as a draft PR with `[WIP]` in the title. +- Empty H2 headings (a heading followed by no content, then another heading) are a sign of a half-done split — finish the section or remove the heading. +- Stub integrations (`integrations/homebridge.md`, `integrations/domoticz.md`) are fine as long as they're honestly framed as stubs and link to the upstream project. Stubs that pretend to be complete docs aren't. + +### 2.5 Information scent in titles, slugs, and sidebar + +- **Page titles are promises.** A page called "Quick Start" should teach you to start quickly. If it's a list of external blog links, name it `external-resources.md`. +- **Sidebar group matches the page mode.** A "Getting started" sidebar entry that points to a reference page sets the wrong expectation. +- **Slugs are URLs forever.** Don't rename casually. If you must, add a redirect in [`astro.config.mjs`](./astro.config.mjs) under `redirects:` so old links keep working. + +### 2.6 Cite the source + +For any non-trivial claim — calibration values, board recommendations, behavior of an MQTT topic — cite the source inline. Acceptable sources, in rough order of authority: + +1. The firmware source (link to a specific file/line on `main` or a tag). +2. A maintained canonical-pinned [Discussion](https://github.com/ESPresense/ESPresense/discussions). +3. A specific Discussion or Issue thread (link to the comment, not just the thread). +4. A maintainer's blog post or video — only when the above don't exist. + +"I read it on Discord" is not a source. Pull it into Discussions or a docs page first. + +--- + +## 3. The defects we keep finding + +These came out of the [ESPA-38](https://github.com/ESPresense/ESPresense/issues) audit walking every page on the site as of 2026-05-10. They aren't theoretical: + +- **Mixed-mode pages.** `companion/configuration.md` is reference + how-to + explanation in one 319-line file. The Kalman-filter section is genuinely good explanation, but it's invisible under three config tables. → Split. +- **Stale UI labels.** "Settings → Apps / Apps Store" is the Home Assistant UI from before the Add-ons rename. Screenshots showing the old labels date the whole page. +- **Inconsistent topic prefixes.** `room_presence/#` in one example, `espresense/#` in the next. Pick one (it's `espresense/`). +- **Placeholder values that don't run.** `host: your_host` in the External MQTT block. A reader can't verify a config that won't connect. +- **Pages that are link dumps.** `guides/technical.md` is 20+ academic PDFs with no commentary. Useful raw material; not a docs page. Either turn it into real explanation citing 3–5 of them, or move it out of the public docs. +- **Component-only pages.** `troubleshooting/terminal.mdx` is 9 lines and an embedded ``. A first-time user lands on a black box. Always wrap a component with: what it does, browser requirements, what a healthy result looks like. +- **Empty H2s.** Two consecutive `## ` headings with no content between them — a sign of an abandoned split. `apple.mdx` had this; don't ship it. +- **No freshness line, anywhere.** Before this contributing guide, no page on the site told the reader which firmware it was verified against. We're backfilling. Don't add to the deficit. +- **Affiliate-link rot.** Amazon/AliExpress links in `devices.md` and `nodes.md` go stale. If you add a board recommendation, link the manufacturer page first and the marketplace as a secondary "where to buy." + +If you spot one of these in a page you're touching, fix it in the same PR — don't paper over it. + +--- + +## 4. How to submit a docs PR + +### 4.1 Setup + +You need Node 22 (see [`.nvmrc`](./.nvmrc)) and npm. Then: + +```sh +npm install +npm run dev +``` + +The site renders at . Hot reload works — save a `.md` or `.mdx` file and the browser refreshes. + +To check the production build before pushing: + +```sh +npm run build +npm run preview +``` + +The site is built with [Astro](https://astro.build/) and [Starlight](https://starlight.astro.build/). Pages live under `src/content/docs/` as Markdown (`.md`) or MDX (`.mdx`). The sidebar is configured in [`astro.config.mjs`](./astro.config.mjs). + +### 4.2 Branch and commit + +- Branch off `main`. Name it descriptively: `docs/calibration-how-to`, `docs/refresh-reference-fw-4.0.6`, `fix/typo-apple-enrollment`. +- One PR, one logical change. A typo fix and a page split shouldn't share a commit. +- Commit messages: imperative mood, present tense — "Add calibration how-to" not "Added calibration how-to". + +### 4.3 Open the PR + +Title: short and specific. "Calibration how-to with Discussions failure-mode triage" beats "calibration page". + +Body should cover: + +- **What** changed and **why**. +- **Diataxis mode** of any new or rewritten page. +- **Tested on** which firmware version and which board (or "site preview only — no firmware behavior changed"). +- **Screenshots** if the page has visible UI changes (drag/drop the image into the PR body — GitHub uploads it). +- **Linked issue or Discussion**, if applicable. + +If you used a draft because you want early feedback, mark it as a GitHub draft and say what you want eyes on. + +### 4.4 What to expect on review + +- A maintainer (currently [@DTTerastar](https://github.com/DTTerastar)) is auto-assigned. Expect a first response within ~3 days. Quicker on Discord if it's urgent. +- Reviews focus on: Diataxis mode, the [quality bar](#2-the-docs-quality-bar) above, voice ([§5](#5-the-voice)), and accuracy of any firmware/UI claim. +- "Can you re-test against the latest firmware tag?" and "Can you cite the source for that number?" are normal asks, not pushback. +- Small typo fixes can land same-day. New pages or restructures usually involve one round of revisions. +- We squash-merge. Your commit history on the branch doesn't need to be tidy. + +### 4.5 After merge + +- Cloudflare Pages picks up `main` and deploys to within a few minutes. +- If you broke a known URL (renamed a slug, deleted a page), you should have already added a redirect in `astro.config.mjs`. If you forgot, open a follow-up PR. + +--- + +## 5. The voice + +Read [`approach.mdx`](./src/content/docs/approach.mdx) and [`guides/calibration.md`](./src/content/docs/guides/calibration.md) before you write. They're the model. + +The site's voice is: + +- **Direct.** "Place the beacon exactly 1 m from the reference node." Not "It is recommended that the beacon be positioned approximately one meter from the reference node." +- **Helpful.** Tell the reader what setting fixes their symptom up front. The 30-second triage table at the top of the calibration page exists because most readers landed there panicked. +- **Occasionally dry.** "Cranking RSSI@1m down to 'see further' is the wrong knob — it just makes other distances inaccurate" is allowed. So is calling a 9-line page "a black box." Don't reach for jokes; do trust the reader to handle a flat statement of fact. +- **Plain talk only.** No corporate jargon. We don't have "stakeholders" or "leverage synergies." We have nodes, beacons, and a reader trying to figure out why their phone reads 3 m away when it's in their pocket. +- **Second person, present tense.** "You set this once, globally." Not "users will need to set this once." +- **Short sentences carry the load.** Long sentences are reserved for hedged technical claims that genuinely need the qualifier. + +What we avoid: + +- Marketing copy. ESPresense is a hobbyist project that grew up; the docs match. +- "Simply." If a step were simple, the reader wouldn't be reading the docs. +- Apologizing for the project ("We know the calibration UI is confusing…"). State the current behavior clearly and link to the relevant Discussion if you'd like to see it improved. +- Threats and exclamation points. The reader is already frustrated; don't pile on. + +--- + +## 6. Common contributions, with shape + +If your contribution is one of these, here's the shape we're looking for. + +**Fixing a typo or stale link.** Single commit, single file. No need for a freshness-line update. Squash-merges same-day. + +**Updating a page against a new firmware release.** Walk every command and config option mentioned. Update the freshness line at the top. If something now behaves differently, note the version it changed in. Coordinate with the [Tech Lead](https://github.com/ESPresense/ESPresense/discussions) before stating "what the firmware does" — don't guess. + +**Adding a new how-to.** Pick a single, specific task. Don't try to be exhaustive. Cite the Discussions thread or Issue that motivated it. Add a freshness line. Add the page to `astro.config.mjs` sidebar in the right group. + +**Adding a new integration.** Stubs are fine if they link upstream and say "PRs welcome." Full integration docs should follow the shape of `integrations/home-assistant.md` (auto-discovery first, manual config second, troubleshooting last). + +**Splitting a mixed-mode page.** Open a tracking issue first so we can coordinate redirects and sidebar changes. The split should land as one PR, not several — readers shouldn't see a half-split state in production. + +**Restoring a Discussions answer to a docs page.** Pick a question that has been asked three or more times. Convert the canonical answer into either a how-to (if it's procedural) or a reference page (if it's a value/topic/option). Link the Discussion forward to the new page; the Community Manager adds a "see the docs page" pointer at the top of the Discussion. + +--- + +## 7. When to ask before opening the PR + +You don't need permission for typos, link fixes, freshness updates, or screenshot refreshes. Open the PR. + +For larger changes, drop a note in [Discussions](https://github.com/ESPresense/ESPresense/discussions) or [Discord](https://discord.gg/jbqmn7V6n6) first if you're: + +- **Restructuring the sidebar** or renaming pages (URL stability matters). +- **Deleting a page** (someone may be linking to it). +- **Stating new firmware behavior** that isn't already documented (Tech Lead needs to confirm). +- **Adding a translation.** We don't currently maintain translations and would need to commit to keeping them current before accepting one. + +--- + +## 8. License + +By contributing, you agree your contribution is licensed under the same license as the repo. Contributions are credited via the GitHub commit history; major contributors also get a line in [`credits.md`](./src/content/docs/credits.md). + +--- + +*Last revised 2026-05-11 against firmware v4.1.0b0. If something on this page is out of date, it's also fair game for a PR.* diff --git a/README.md b/README.md index 23f6f7e..f66c6b6 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,45 @@ # ESPresense.com -Source for https://espresense.com + +Source for , the documentation site for [ESPresense](https://github.com/ESPresense/ESPresense) — an ESP32-based indoor positioning system. + +Built with [Astro](https://astro.build/) and [Starlight](https://starlight.astro.build/). Deployed to Cloudflare Pages from `main`. + +## Develop locally + +You need Node 22 (see [`.nvmrc`](./.nvmrc)) and npm. + +```sh +npm install +npm run dev +``` + +The site renders at with hot reload. + +Other scripts: + +```sh +npm run build # production build to ./dist +npm run preview # serve the production build locally +``` + +## Where pages live + +- `src/content/docs/` — Markdown (`.md`) and MDX (`.mdx`) pages. +- `astro.config.mjs` — sidebar layout and URL redirects. +- `public/images/` — committed images (screenshots, diagrams). + +## Contributing + +Read **[CONTRIBUTING-docs.md](./CONTRIBUTING-docs.md)** before opening a PR. It covers: + +- Which [Diataxis](https://diataxis.fr/) mode (tutorial / how-to / reference / explanation) fits which kind of page. +- The docs quality bar — verified commands, dated freshness lines, real diagrams, no abandoned drafts. +- How to submit a PR and what to expect on review. +- The voice we're aiming for. + +For the firmware and the desktop daemon, see the upstream repos: + +- Firmware: +- Companion: + +Questions: [Discussions](https://github.com/ESPresense/ESPresense/discussions) or [Discord](https://discord.gg/jbqmn7V6n6). From 25b4fd5896793528e0bf3213f0e931d58e9af18b Mon Sep 17 00:00:00 2001 From: Terastar-Paperclip Date: Mon, 11 May 2026 00:12:28 -0400 Subject: [PATCH 2/2] Fix MD038: remove internal trailing space in empty-H2 example CodeRabbit flagged the inline code span `## ` as MD038 (no-space-in-code). Drop the trailing space and reword the surrounding clause so the meaning is unchanged. Co-Authored-By: Paperclip --- CONTRIBUTING-docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING-docs.md b/CONTRIBUTING-docs.md index a74e3c2..94758c2 100644 --- a/CONTRIBUTING-docs.md +++ b/CONTRIBUTING-docs.md @@ -105,7 +105,7 @@ These came out of the [ESPA-38](https://github.com/ESPresense/ESPresense/issues) - **Placeholder values that don't run.** `host: your_host` in the External MQTT block. A reader can't verify a config that won't connect. - **Pages that are link dumps.** `guides/technical.md` is 20+ academic PDFs with no commentary. Useful raw material; not a docs page. Either turn it into real explanation citing 3–5 of them, or move it out of the public docs. - **Component-only pages.** `troubleshooting/terminal.mdx` is 9 lines and an embedded ``. A first-time user lands on a black box. Always wrap a component with: what it does, browser requirements, what a healthy result looks like. -- **Empty H2s.** Two consecutive `## ` headings with no content between them — a sign of an abandoned split. `apple.mdx` had this; don't ship it. +- **Empty H2s.** Two consecutive `##` headings with nothing between them — a sign of an abandoned split. `apple.mdx` had this; don't ship it. - **No freshness line, anywhere.** Before this contributing guide, no page on the site told the reader which firmware it was verified against. We're backfilling. Don't add to the deficit. - **Affiliate-link rot.** Amazon/AliExpress links in `devices.md` and `nodes.md` go stale. If you add a board recommendation, link the manufacturer page first and the marketplace as a secondary "where to buy."