A notebook for thinking in systems

The technical writing field guide

A complete working example: mathematics, code, diagrams, references, and a reading series.

NoteAbout this article

This is the first article and a formatting reference for this site. The code and measurements are illustrative; they do not report a new research result. Open posts/writing-systems/index.qmd to inspect the source behind every example.

1. Words, structure, and emphasis

A useful systems article starts with a question, states its assumptions, and makes its evidence inspectable. The same structure works for a paper discussion, a model, or an experiment.

Use bold for a key claim, italics for emphasis, both sparingly, and inline_code for identifiers. You can mark superseded wording, highlight a condition, show H₂O and x², or write an escaped symbol: *.

A link to the original FLP paper gives readers a route to the source. An internal link can point directly to the mathematics section. A footnote is useful for a qualification that would interrupt the main argument.¹

Third-level heading

Use headings to express the argument’s structure, rather than its visual size.

Fourth-level heading

Short supporting detail belongs here.

Fifth-level heading

Available when a long reference needs an additional level.

Sixth-level heading

Usually unnecessary in a normal article; included here as a rendering example.

State the failure model before discussing the failure detector.

This is an original editorial note, not a quotation from a cited paper.

---

2. Lists and definitions

A preparation checklist:

• State the question.
• Record the assumptions.
  • What may fail?
  • What does the network guarantee?
• Make the artifact available.

A procedure:

1. Start from a baseline.
2. Change one assumption.
3. Compare the observed outcomes.

A static task list:

• Publish the model’s assumptions.
• Label illustrative measurements.
• Add a real experimental dataset.

Safety

A requirement that a forbidden outcome never occurs.

Liveness

A requirement that progress eventually occurs under stated assumptions.

3. Mathematics

Inline mathematics fits naturally into a sentence: a strict majority of n participants has size q = \lfloor n/2 \rfloor + 1.

For a fixed universe V, let Q_1,Q_2\subseteq V. If both sets contain more than half of V, then

\begin{aligned} |Q_1 \cap Q_2| &= |Q_1| + |Q_2| - |Q_1 \cup Q_2| \\ &\ge |Q_1| + |Q_2| - |V| \\ &> 0. \end{aligned} \tag{1}

Equation 1 establishes set intersection. It is not, by itself, a consensus correctness proof.

A matrix and a piecewise function are also supported:

A=\begin{bmatrix}0&1&0\\1&0&1\\0&1&0\end{bmatrix},\qquad f(x)=\begin{cases}1 & x>0,\\0 & x\le 0.\end{cases}

Theorem 1 (Majority intersection) Any two strict-majority subsets of the same finite universe intersect.

Proof. The set-cardinality identity in Equation 1 gives a strictly positive lower bound on the size of the intersection. Therefore the intersection is nonempty.

4. Code: Rust, Go, and TLA+

These are displayed code blocks. The blog build does not execute them.

Rust

use std::collections::BTreeSet;

fn has_majority(acks: &BTreeSet<u64>, voters: &BTreeSet<u64>) -> bool {
    let votes = acks.intersection(voters).count();
    !voters.is_empty() && votes > voters.len() / 2
}

This toy helper counts distinct acknowledgements from members of a fixed voter set. It does not handle terms, configuration changes, or authentication.

Go

package quorum

func HasMajority(acks, voters map[uint64]struct{}) bool {
    votes := 0
    for id := range acks {
        if _, ok := voters[id]; ok {
            votes++
        }
    }
    return len(voters) > 0 && votes > len(voters)/2
}

TLA+

The project includes a small custom syntax definition for tla; it highlights common constructs without pretending to be a parser or model checker.

--------------------------- MODULE AckSet ---------------------------
EXTENDS FiniteSets
CONSTANT Nodes
VARIABLE acks

Init == acks = {}
Ack(n) == /\ n \in Nodes \ acks
          /\ acks' = acks \cup {n}
Next == \E n \in Nodes : Ack(n)
TypeOK == acks \subseteq Nodes
Spec == Init /\ [][Next]_acks
=====================================================================

Line numbers and annotations

quorum.rs

let voters = BTreeSet::from([1, 2, 3]);
1let acks = BTreeSet::from([1, 2]);
2assert!(has_majority(&acks, &voters));

1

Repeated acknowledgements cannot create additional distinct votes.

2

This assertion tests one example, not all behaviours of a protocol.

Collapsible code

Show the small Go example

// A displayed example, not executed by the build.
func majoritySize(n int) int { return n/2 + 1 }

A literal command and its output can be displayed separately:

python3 scripts/blog.py build

Building a static website from versioned source files.

5. Mermaid: a live browser-rendered diagram

flowchart TD
  A[Receive acknowledgement] --> B{Known voter?}
  B -->|No| C[Ignore]
  B -->|Yes| D[Add to distinct set]
  D --> E{Strict majority?}
  E -->|No| F[Wait for more]
  E -->|Yes| G[Report threshold reached]

This depicts only the helper’s counting logic. Reaching a numerical threshold does not establish all the conditions a real protocol requires.

6. PlantUML: external rendering, local delivery

Figure 1: Illustrative request and acknowledgement exchange, not a full consensus protocol.

Figure 1 is generated from the PlantUML source by an external PlantUML-compatible renderer. The returned SVG is stored in this repository and served with the site. Rendering details and the source checksum are recorded in acknowledgements.svg.render.json.

To update it after editing the .puml file:

python3 scripts/blog.py plantuml posts/writing-systems/acknowledgements.puml

No Java or PlantUML installation is required locally. The ordinary blog build uses the saved SVG and does not need the rendering service. Only public diagram source should be sent to a public renderer.

7. Tables, figures, and downloadable data

The following values are invented formatting data, not benchmark results.

Table 1: Illustrative values for a table.

Scenario	Participants	Example latency (ms)
Baseline	3	12
Additional delay	3	27
Larger group	5	19

A table can be referenced as Table 1. Download the same illustrative data.

Figure 2: Illustrative latency values; no empirical results are represented.

Figure 2 is a local vector image with alternative text. SVG is useful for diagrams that should remain sharp at different screen sizes.

8. Callouts, tabs, and disclosure

NoteNote

Record definitions and context close to the claim they qualify.

TipTip

Link the exact commit or release used for an experiment.

ImportantImportant

A timeout is evidence of missing observations, not a proof that a process has crashed.

WarningWarning

The scope of a guarantee depends on its assumptions.

CautionCaution — click to expand

A small successful test cannot replace an argument covering the required behaviours.

Assumptions

A fixed voter set and distinct acknowledgements.

Observation

A numerical threshold is reached.

Limitation

The example does not establish consensus safety or liveness.

Additional implementation detail

This is an HTML disclosure element. Markdown inside it can include emphasis, links, and code.

9. Citations and provenance

For example, the FLP paper is cited as Fischer et al. (1985). A parenthetical citation looks like this (Fischer et al. 1985). The reference is stored in the adjacent references.bib file.

A research post should identify which statements come from the cited source and which are the author’s interpretation. Here, the citation demonstrates bibliography rendering; this article is not a summary of FLP.

10. Article history

• 2026-09-21: Initial formatting reference. All example measurements are synthetic.

Series: Writing about systems

Part 1 of 1 · suggested reading order

References

Fischer, Michael J., Nancy A. Lynch, and Michael S. Paterson. 1985. “Impossibility of Distributed Consensus with One Faulty Process.” Journal of the ACM 32 (2): 374–82. https://doi.org/10.1145/3149.214121.

Footnotes

1. A formatting example is not a complete statement of a distributed algorithm or its proof obligations.