General writing guide

General writing guide (this article) is a guide to writing articles in this wiki.

The intended audience is someone technically inclined — comfortable reading code and following a logical argument, but not necessarily with a formal background in every subject the wiki covers. Two things to keep in mind while writing:

• Explain things from first principles before introducing notation.
• When a derivation relies on a property that is not self-evident from the notation, it can be worth slipping in a brief reminder in prose at the point of use. One sentence is enough — the article should still be dense, not a textbook.
• Occasional analogies with computer technology (hardware, software, systems) help ground abstract concepts in familiar territory.

Every article opens with the name of the article in bold, followed by 2–3 sentences that define the concept. This paragraph should be self-contained: a reader skimming just the first paragraph should know what the article is about and why it matters.

Each paragraph covers one idea in 3–6 sentences. Where possible, follow a paragraph with a concrete artifact — a code block, equation, or list — that illustrates the idea. Avoid long unbroken stretches of prose.

A section should have a single flavor: either prose, a list, a code block, or equations. Don't mix flavors within a section without a clear reason. A section should contain 2–5 paragraphs. If it grows beyond that, open subsections — and subsections should also stay within 2–5 paragraphs each.

The first section is always the unnamed lead section (no ## heading). Named sections follow once the intro is complete.

There are two kinds of code blocks: snippets and full examples.

A snippet appears inside a concept article to illustrate one idea. It shows only the essential lines — no #include, no main(), no boilerplate. The reader should be able to grasp the point in a few seconds.

A full example is a self-contained MVE (minimum viable example) that the reader can copy, compile, and run as-is. It belongs in a dedicated implementation article, not in a concept article. At the top of the block, include a comment header with three fields: how to compile (if applicable), how to run, and a one-line description.

// compile: gcc -o hello hello.c
// run:     ./hello
// desc:    print "Hello, world!" to stdout
 
#include <stdio.h>
 
int main(void) {
    printf("Hello, world!\n");
    return 0;
}

Python and other interpreted languages omit the compile line:

# run:  python3 hello.py
# desc: print "Hello, world!" to stdout
 
print("Hello, world!")

Prefer explicit variable names over brevity in both kinds.

Inline Greek letters and short expressions ($\alpha$, $e^{i\theta}$, $H^\dagger = H$) are fine mid-sentence. Anything involving fractions, matrices, sums, integrals, or multi-character subscripts belongs on its own display line:

$$X = \begin{pmatrix} 0 & 1 \\ 1 & 0 \end{pmatrix}$$

Use $$...$$ for display equations and $...$ for inline. When equations appear in a derivation, give each step its own display line. Don't embed intermediate steps in sentences — it forces the reader to parse prose and algebra simultaneously.

Write in a direct, technical voice. Avoid marketing language, superlatives, and filler phrases (“it is important to note that”, “as we can see”, “in conclusion”). Don't restate at the end of a section what the section just said. Short, dense paragraphs are better than long ones.

Don't use em-dashes. Don't use them as parenthetical interruptions (“the compiler — not the programmer — inserts”) and don't use them to introduce a list mid-sentence. If you need to add a qualification or aside, rephrase it as a subordinate clause, a separate sentence, or restructure so the idea flows naturally from the main clause.

Analogies from classical computing and embedded systems are welcome and natural — the audience relates to registers, interrupts, and buses more readily than to abstract mathematical structures.

Articles that are not yet complete start with (WIP) in the heading: # (WIP) Article name. The site renders these links in yellow to signal to visitors that the article is in progress.