Add writing and code example rules to the style guide

STYLE.md

@@ -3,11 +3,48 @@
 These rules apply to every page in `docs/`. Follow them when you write or edit a
 page, and check against them when you review one.
 
+## Writing
+
+- Be concise. Say a thing once, clearly, then move on. Don't restate a point in
+  a later section, a summary, or a second example.
+- Start from what the reader wants to do, not from how the product works inside.
+  Explain the mechanism only as far as the reader needs it.
+- Explain a term before you use it, or don't use it. Prefer the reader's words
+  ("step code") to internal ones ("source file", "stripping").
+- Keep each page to its topic. If the reader needs another concept, give one
+  sentence at most and link to the page that explains it.
+- Document what users should do today. Leave out internal team processes,
+  workarounds for features that don't work yet, and edge cases few users hit.
+- Don't add sections for the sake of structure. Skip troubleshooting entries,
+  reference tables, and "Next steps" lists unless each item earns its place. A
+  list of related pages is "Related pages", not "Next steps".
+- Don't copy lists that live in the product, like CLI flags. They go out of
+  date. Point to the source instead, like `openfn compile --help`.
+- Be confident. Write "You can install a new version over the old one", not "You
+  should be able to".
+- Avoid the habits of AI-generated text:
+  - runs of short punchy sentences
+  - claims about the page itself ("This is the most important thing on this
+    page")
+  - words that cheer the result ("Both exports survived")
+  - filler before the point: "It's important to note", "Note that", "Keep in
+    mind". Delete it and start with the point.
+  - marketing words: "seamless", "powerful", "robust", "leverage", "streamline",
+    "comprehensive"
+  - "not just X, but Y", "Whether you're X or Y", and lists of three where two
+    items would do
+  - headings written as questions, like "What are cron jobs?"
+  - bullet lists where a sentence would read better
+
 ## Pages and headings
 
 - Every page has a `title` in its front matter.
 - Start a page's sections at `##` and don't skip levels. Don't make heading text
   bold, and don't repeat the page title as the first heading.
+- A heading says what the section covers without the reader needing the UI in
+  front of them: "Async mode responds before start", not "Async (Before Start)".
+- Don't open a page with a paragraph that lists its sections. The sidebar and
+  table of contents already do that.
 
 ## Links
 
@@ -31,6 +68,8 @@ page, and check against them when you review one.
 
 - Images live in `static/img/` and are linked as `/img/filename`, with alt text
   that says what the image shows. "Screenshot" does not count.
+- Use as few screenshots as the page needs. Each one goes out of date when the
+  app changes. Show the panel you're talking about, not the whole app.
 
 ## Formatting
 
@@ -45,7 +84,29 @@ page, and check against them when you review one.
 - Emphasis markers sit right against the text: `**_like this_**`, not
   `**_like this _**`. With a space inside, the formatting does not show and the
   page prints the markers.
+- Use admonitions sparingly, and keep the tone calm. Don't use `:::danger` or
+  `:::caution` to make a point sound urgent. Give an admonition a title that
+  says what it's about, like `:::warning There's no redirect on edit`.
+- Don't make a list of one item. Write it as a sentence.
+- Don't use em-dashes (—). Use a spaced hyphen ( - ), a comma, or two sentences.
+- Don't use `<Tabs>` to show content the reader needs to compare, like job code
+  and its output. Show them one after the other.
+
+## Code examples
+
 - Code examples must be valid code. Check them before publishing.
+- Use realistic data. Don't name things "Test", and make sample keys and IDs
+  look like the real format. Put the sample value in the code, not in a comment.
+  Say when data is made up.
+- Name variables for what they hold: `state.conditions`, not
+  `state.conditionMappedData`; `diagnosis`, not `item`.
+- Add a short comment above each operation that says what it does and why. Put
+  notes about a line of code in a comment next to it, not in the prose.
+- Keep examples to the point. One test shows how to write a test; five show
+  nothing more.
+- Job examples should tell a story the function reference can't: fetch some
+  data, reshape it, send it on. A one-line example belongs in the function's own
+  docs.
 
 ## Wording and spelling
 
@@ -56,8 +117,14 @@ page, and check against them when you review one.
 - Use American English spelling: "organization", "color", "behavior".
 - It is spelled **adaptor**, never "adapter".
 - Write these names with this capitalization in prose, headings and alt text:
-  **JavaScript**, **Node.js**, **GitHub**, **OAuth**, **CommCare**, **Docker**,
-  **Linux**, **Unix**, **macOS**. Leave code and file paths as they are.
+  **JavaScript**, **TypeScript**, **Node.js**, **GitHub**, **OAuth**,
+  **CommCare**, **Docker**, **Linux**, **Unix**, **macOS**. Leave code and file
+  paths as they are.
+- "Set up" is the verb, "setup" the noun: "set up a credential", "check your
+  setup".
+- Use product names in full and the same way each time: "the AI Assistant", "the
+  Responsible AI Policy". Call a part of the app by the name the rest of the
+  docs use for it.
 - Use "e.g." to introduce an example and "i.e." to restate, never "ie". Put a
   comma after both, like "(e.g., a form submission)".
 - Use the approved terms in `glossary.yml`. If a page uses one of the listed