Software Engineering · Cluster
Documentation
Reference material that stays true.
- 01 The Contract Elements a Function Reference Entry Has to State A signature fixes argument types and little else. Preconditions, ownership, failure modes, and concurrency guarantees are separate obligations that the reference entry has to record explicitly.
- 02 How Doctest Decides Whether a Documented Example Passed A transcript in a docstring is compared against captured output by a specific set of rules. Understanding those rules explains why examples drift and which ones cannot be verified at all.
- 03 Changelogs as a Curated Projection of Commit History A changelog is not a formatted log. It selects changes by who observes them, classifies them against a version bump, and states consequences that no commit message contains.
- 04 Heading Anchors and the Silent Failure of Fragment Links A fragment link is resolved in the browser and never requested from the server, so a renamed heading breaks every inbound reference without producing a single 404.
- 05 What an API Doc Generator Can Recover From Source Alone Parsing and runtime introspection produce different documentation from the same code. Which one a toolchain uses decides what it can see, what it silently omits, and what it can never know.
- 06 Stable Error Codes as Documentation Identifiers Human-readable messages change with wording and locale. A code that never changes, is never reused, and is documented once is what lets callers and support engineers agree on which failure occurred.
- 07 Deterministic Checks That Keep a Documentation Build Honest A build can verify markup, references, examples, and terminology without judgement. Separating those mechanical assertions from editorial taste is what makes a failing build mean something.
- 08 Ranking Documentation Search When the Query Is an Error String Documentation queries are lookups, not explorations. Identifier tokenisation, field weighting, and version duplication decide whether the entry a reader needs appears at all.
- 09 Serving Several Documentation Versions From One URL Space Versioned documentation is a URL design problem before it is a content problem. Path layout, redirect policy, relative links, and canonical hints decide whether a reader stays on the release they are running.
- 10 Detecting Drift Between Reference Material and the Code It Describes Documentation goes stale one claim at a time. Separating checkable claims from judgement calls shows which kinds of drift a build can catch and which only review can.