Editorial standard

Edition: 2026-07-12 · Audience: technical readers and researchers
Register: clear scientific English — precise, without a wall of jargon.

1. Voice and notation

Short paragraphs + numbered definitions

Avoid: Walls of undifferentiated bullets

Standard scientific names on first use, then short form

Avoid: Undefined acronyms

Inline math $E = mc^2$ or plain E = mc²

Avoid: Broken tokens like $$ $Z$ $$

“We write…”, “Define…”, “Theorem-style claim:”

Avoid: Marketing superlatives (“ultimate”, “revolutionary”)

Active, present tense for definitions

Avoid: Filler (“in order to”, “it is important to note that”)

Definitions use a fixed shape:

Definition (Name). Statement in one or two sentences.
Notation. Optional symbols.
Example. One concrete case.

2. Chapter card (top of every chapter)

Every chapter begins with:

Title (# …)
Part label (General · Engineering · Computer Science · Playbooks)
At a glance — 3–6 bullets of claims
Keywords — comma-separated
Online references — live Wikipedia / primary URLs
Offline snapshots — local screenshots under .gitbook/assets/snapshots/ so the book survives link rot
Body — main content
See also — internal links
Glossary terms introduced — list of keys pointing to GLOSSARY.md

3. References policy

Wikipedia

Rule: Link EN (and PT/FR when primary) + embed-style figure with screenshot + caption = URL + retrieval date

Papers / books

Rule: Prefer DOI or stable publisher URL + short citation

GitHub

Rule: Org/repo root + pin commit or main note in caption

Social embeds

Rule: Keep {% embed %} where useful; always pair with offline snapshot when the claim is load-bearing

Screenshot command (maintainer):

CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
"$CHROME" --headless=new --disable-gpu --window-size=1280,1800 \
  --screenshot=docs/.gitbook/assets/snapshots/wiki-<slug>.png \
  "https://en.wikipedia.org/wiki/<Page>"

4. Scientific simplicity

Explain as if teaching a careful undergraduate:

State the object of study.
Give the minimal formalization.
Give one worked intuition.
Point to where the deep literature lives (links + snapshots).

Do not remove depth from long chapters; add structure (numbered parts, definition boxes, cross-links) instead of deleting material.

5. Completeness checklist (per chapter)

[ ] Chapter card present
[ ] At least one Wikipedia (or primary) live link
[ ] At least one offline snapshot figure
[ ] Keywords + glossary keys
[ ] See also ≥ 2 internal links
[ ] English pass (no broken HTML entities as prose, no empty <a class="button">)
[ ] Math notation readable

Applies to all paths under this library.