Ivan's wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
# General writing guide
**General writing guide** (this article) is a guide to writing articles in this wiki.

## Audience

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.

## Article structure

### First paragraph

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.

### Paragraphs

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.

### Sections

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.

## Code blocks

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.

```c
// 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:

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

print("Hello, world!")
```

Prefer explicit variable names over brevity in both kinds.

## Equations

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:

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.

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



## Tone

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.

## WIP articles

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.