Differences

This shows you the differences between two versions of the page.

--- general-writing-guide [June 11, 2026 at 00:03] – Ivan Janevski
+++ general-writing-guide [June 11, 2026 at 07:44] (current) – external edit 127.0.0.1
@@ Line 2: / Line 2: @@
 **General writing guide** (this article) is a guide to writing articles in this wiki.
-## Structure
+## Audience
-### Main section
-Every article should preferably start with a main section followed by a few paragraphs. The first paragraph should preferably start with the name of the article in bold (just as it did in this article) followed by a few sentences that further describe the concept.
+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
-Paragraphs should describe one main idea in 3-6 sentences. Preferably (though not necessarily so) this idea is better described by an artifact just below the paragraph e.g. a code block, equation or an image. A section should contain 2-5 paragraphs. If there are too many paragraphs, it's fine to open subsections but then they have to contain 2-5 paragraph as well.
+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
-Sections should have a certain flavor. For example, if a section is titled "List of concepts related to X" it should only contain a list and no additional description. Similarily, if a section is titled "C++ code illustrating X" it should only contain a code block and preferably no prose. Any additional description can be added in the code comments. Same goes for equations. A section like "Equations of X" or "" should only contain LaTeX `$$ ... $$` and little description. It should only
-The first section should preferably always start with a paragraph that starts with the name of the article in **bold** followed by a short description (two-three sentences) of what the concept is. The subsequent paragraphs should expand the concept in the most nautral way.
+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.
-### Code block
+The first section is always the unnamed lead section (no `##` heading). Named sections follow once the intro is complete.
-A code block is a larger piece of code that. Preferably all code blocks should be self-contained MVEs (minimum viable examples). At the top there should be a comment block on how to compile and run the code.
-```cpp
+## Code blocks
-// Compile:     g++ main.c -o main
-// Run:         ./main
+There are two kinds of code blocks: **snippets** and **full examples**.
-// Description: echo "Hello world!"
+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()
+int main(void) {
-{
+    printf("Hello, world!\n");
-    printf("Hello world!");
     return 0;
 }
 ```
-### Equations
+Python and other interpreted languages omit the compile line:
-Equations should be written in LaTeX. Math symbols like greek letters $\alpha,\beta,\gamma$ are fine to embed directly into paragraphs but heavy-duty equations that involve matrices, integrals, fractions, sums and so on should preferably put in their own line. For example the following is a matrix for Pauli $X$ gate
+```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:
 $$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.
+## 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.