Writing Style

Writing guidelines for clstr challenge documentation.

Audience

Write for capable peers: mid-level+ engineers who can research, make implementation choices, and work on complex problems.

State what the system needs to accomplish, not how to build it. Point to possible approaches, considerations, and resources, but let readers make implementation choices.

Pedagogy

Structure learning through progressive disclosure. Start each challenge with the simplest version of a problem, then add complexity only after the foundation is solid. Make each stage build on previous work so the progression feels natural rather than arbitrary.

Introduce one major capability per stage: one testable system behavior that builds on previous work. Supporting concepts can appear as needed, but each stage should add one clear building block to the system. Describe stages based on the capability they add, not the mechanism used to achieve it. This keeps focus on what the system accomplishes at each stage. Where current decisions anticipate future stages, say so briefly. If a reader is making a trade-off now that they will revisit later, a short forward reference keeps the progression coherent.

Each new stage must be backwards compatible with all prior stages. CI runs clstr test --so-far, which tests every stage up to and including the current one on every push. A new stage must not change the external contracts (HTTP endpoints, response formats, error messages) defined by earlier stages. Implementations that were passing before must continue to pass.

Constrain interfaces and contracts that affect testing or compatibility. Leave internal implementation details (data structures, algorithms, optimizations) to the reader’s judgment.

Link to external resources when you introduce concepts. Point to tutorials, papers, lectures, or reference implementations: whatever explains it best. Don’t replicate explanations that already exist; point to the best resources and move on.

Voice & Tone

Address the reader directly using second person (“you”) and active voice. Write as if you’re giving clear directions to a colleague, not lecturing from a podium. Use simple, everyday language.

Get to the point immediately. Skip introductory context about why topics are important. Your reader already has that context. Brief section transitions are fine, but avoid elaborate setup. Do explain the reasoning behind specific constraints or design choices you’re imposing.

Maintain a matter-of-fact tone. Reassurance and light tone are fine in introductions and conclusions, but keep the technical sections direct and free of cheerleading. An occasional emoji is fine.

Formatting

Structure each stage with a brief introduction that orients the reader: what they’re building, what it doesn’t do yet, and optionally how it connects to what comes next. This is distinct from the “skip introductory context” rule, which applies to within-section prose, not stage openers. Follow the intro with precise specifications, implementation guidance, and testing instructions. Optionally include a debugging section with example test failures or debugging techniques. When showing failures, provide actionable guidance: expected versus actual output, then what to check or what might have gone wrong.

When defining API contracts, data formats, or expected behaviors, be exact. Include complete endpoint specifications with methods, parameters, responses, and literal error messages. Specify data constraints explicitly. The goal is removing ambiguity about what to build without prescribing how to build it.

Don’t use callout blocks (:::note, :::tip, :::warning, etc). Embed important information in the surrounding prose instead.

Use code blocks to show test invocations, command-line usage, and expected outputs: not implementation code or algorithms. Readers should see how to verify their work and what correct behavior looks like. When test behavior isn’t obvious from output alone, briefly explain what the test does, especially when it affects implementation constraints (which signals, timing requirements, error conditions to handle).

Test Names

Name tests as declarative statements that read like assertions: “Leader Election Completes”, “Partition Enforces Quorum”, “Followers Redirect to Leader”. The test name should state what must be true, so a failure is immediately informative without reading the test body.