Docs

Writing PiFinder Documentation

PiFinder's published documentation is a Sphinx site written in reStructuredText. Your job with this skill is to add or improve pages that a reader moves through without friction: the same rST conventions, the same cross-reference style, and the plain, consistent prose described under The house voice below. That voice is the part most likely to slip, so read it before you write.

Orient first (and avoid the big trap)

The real documentation lives in docs/source/*.rst. It is built by Sphinx and published to pifinder.readthedocs.io.

The trap: docs/*.md (e.g. docs/user_guide.md) are four-line redirect stubs pointing at Read the Docs. They are not the docs. If you find yourself editing a .md file under docs/, stop — you're in the wrong place. Edit the matching docs/source/<name>.rst.

The page set (registered in docs/source/index.rst):

Two hardware revisions are live

The manual covers rev4, v3 and v2.5 PiFinders. rev4 is the current hardware, fully enabled in software from v2.6.1, and it differs from v3 in ways a reader will hit immediately:

Three rules for writing across both:

1. Write rev4 as the default case. Plain prose describes rev4; v3/v2.5 differences go in a .. note:: under the passage they affect — not the other way round, and not balanced "on rev4… on v3…" pairs in every paragraph.
2. Call it "rev4" — never "v4" or "V4". Leave v3 and v2.5 named as they are; those names are on the website, on invoices and throughout Discord. Do not retro-rename them to rev3/rev2.5.
3. Logical key names are identical on both. "Press RIGHT", "hold SQUARE and press +" are correct everywhere. Explain the joystick once, early, and then trust the reader — don't append "(or push the joystick right)" throughout.

Press the power button on top to start the PiFinder.  To shut down, press it again — the
screen asks you to confirm, and a second press powers the unit off.

.. note::
   On v3 and v2.5 PiFinders, power is a white slide switch rather than a button, and you
   shut down from the Quick Menu instead.

build_guide.rst and BOM.rst describe the v3/v2.5 through-hole build only. rev4 build files are not published, so do not add rev4 content or scoping notes to those two pages.

Section in user_guide vs standalone page — a topic earns its own page only when readers arrive at it directly with a task in hand (search, a Discord answer, a cross-page link) and it is separable from the guide's operate-and-observe storyline (a sentence + link suffices in its place). Otherwise it's a user_guide section. Standalone page URLs get linked from the wild — don't merge or rename pages casually. Rationale and worked examples: docs/adr/0015-user-docs-page-granularity.md.

Before writing a single line, read the page you're about to touch (or the closest sibling). Mirror its structure: heading depth, how it introduces images, how it refers to other pages, how long its sections run.

Do not mirror its sentence style. Most of the manual was written before the house voice below was settled, so the neighbouring paragraphs are a worked example of layout and a poor guide to prose. Take the structure from the page and the sentences from the rules.

Get the facts right

Documentation that's confidently wrong is worse than none. Two bundled references hold hard-won, authoritative product knowledge — consult them before writing about anything you're not certain of, and prefer their facts over your own assumptions about how the hardware behaves.

• references/product-knowledge-base.md — the big one. Distilled from real support threads, it covers product versions/configs, setup & first use (power/charging, GPS lock, focus, brightness, sleep mode), common issues, connectivity, catalogs, warranty, an FAQ, and a troubleshooting decision tree. It's long, so jump to the relevant ## section rather than reading top to bottom. Especially useful for the troubleshooting/setup material that the user guide and quick start cover.
• references/hardware-support.md — diagnosis and troubleshooting detail (plate-solving focus/exposure, alignment, power, GPS interference, build issues).

Crucial framing: both files were written to guide customer-support emails, not docs. Mine them for facts — specs, defaults, behaviors, the steps that actually fix a problem — but never carry over their support voice (reassurance scripts, escalation advice, sign-offs). Rewrite every fact in the manual's own voice. If anything there conflicts with the code or the existing docs, trust the code/docs and flag the conflict to the user rather than documenting the discrepancy.

The house voice

The manual follows a simplified technical English style. Write short, plain sentences. Use the same word for the same thing every time.

This matters more here than in most software documentation. The reader is usually outdoors in the dark. They are cold, their night vision is fragile, and they are often reading on a phone one-handed. PiFinder's own interface ships in German, Spanish, French and Chinese, so a large share of readers work through the English manual as a second language. Short, predictable sentences survive those conditions. Elegant long ones do not.

Simplified does not mean cold. The warmth comes from the words you choose and from talking to the reader directly. It does not come from long sentences or decorative punctuation. Keep the warmth. Shorten the sentences.

The seven rules

1. One idea per sentence. Do not join two sentences with an em-dash or a semicolon. Use a full stop.
2. Use active voice. Name the actor. Use the passive only when the actor is genuinely unknown or does not matter.
3. Start instructions with a command verb. "Select Focus." A short condition or location may come first: "From the main menu, select Settings." Do not bury the verb behind a clause.
4. Use simple tenses. Simple present carries almost everything in a manual.
5. Avoid auxiliary chains. Write "you see", not "you will be able to see". Plain "can" and "may" are fine.
6. Stack at most three nouns. Hyphenate the modifier or add a preposition when a string grows: "the exposure time setting for the camera", not "camera exposure time setting".
7. Use one word per concept. See the table below.

Rule 7 is the one that decays fastest, because every writer reaches for a synonym to avoid repetition. Repetition is correct here. These are the terms that drift most in the current manual:

The full table, the reasoning behind each choice, worked before/after examples, and patterns for replacing em-dashes live in references/ste-style.md. Read it before writing or revising more than a paragraph.

Apply this to text you write, not to text you pass by. The manual predates this style and still contains 259 em-dashes and 83 semicolons. Convert opportunistically, the same way you convert screenshots: text you write fresh follows every rule, text you are already revising gets converted in the same edit, and everything else stays as it is. Do not start a mass style pass. If a page needs one, say so and let the user decide.

• Talk to the reader as "you." "You then see the Main Menu."

• Keep the tone calm and confident. Reserve exclamation points for the rare genuinely delightful moment. Prefer plain, declarative sentences otherwise.

• Say it once. Cut throat-clearing ("In order to…", "You should note that…"), redundant restatement, and hedging. When a procedure runs to more than two or three ordered steps, use a numbered list rather than a chain of "To begin… Next… Once you have…" paragraphs.

• Write complete sentences. Do not open with a conjunction. Never begin a sentence with "And". Join the thought to the sentence before it, or rephrase. The same goes for opening with "But" or "So."

• Explain the why, but compress it. A reader who understands the reason trusts the instruction. Keep the why, but state it in a clause rather than a paragraph. "The PiFinder dims the screen after a while to save battery and prevent glare" earns its keep. A three-sentence aside reassuring the reader that this is normal does not. When a caveat genuinely needs more room, put it in a .. note:: rather than swelling the main flow.

• Plain language over jargon. When a technical term is unavoidable (plate solving, alt/az), define it in passing the first time, the way the quick start glosses "plate solving" as taking continuous pictures and comparing them.

• Hardware keys are bold, uppercase: the UP / DOWN arrows, RIGHT, LEFT, the SQUARE button, + and -. Menu and screen names are written in Title Case as they appear on the device (Settings Menu, Object Details, Push-To).

• Describe menu navigation as a prose chain, not a glyph path. Walk the reader along the route in plain verbs: "From the main menu, select Settings, scroll down to Advanced, then select PiFinder Type." Do not write Settings → Advanced → PiFinder Type. Arrow paths belong to the Mermaid menu trees in menu_map.rst. In running prose they read as jargon.

  Use select and scroll throughout, never "choose", "pick", or "go to". A route that mixes verbs makes the reader wonder whether the steps differ. The manual gets this wrong in several places, so copy the rule rather than the neighbouring page.

  Name each step in Title Case as it shows on the device. Anchor it when that helps the reader find it ("near the bottom of the main menu", "at the top of the Start menu"). For a destination you point at more than once, link it with a :ref: cross-reference to its section instead of respelling the whole path each time.

Voice check. Both of these carry the same information.

Yes. Hold SQUARE and press + to brighten the screen, or - to dim it. At a dark site you can turn it right down to preserve your night vision.

No. Brightness is adjustable via the SQUARE modifier key in combination with the increment/decrement keys — at a dark site the display can be turned right down, which will help to preserve your night vision.

The second version breaks four rules at once. It is passive ("is adjustable", "can be turned"). It joins two sentences with an em-dash. It says "display" where the manual says "screen". It chains auxiliaries ("will help to preserve"). None of those faults is dramatic on its own. Together they are what makes documentation tiring to read at 2am.