Topic: documentation
-
Print stylesheets: making a web page usable on paper and as PDF
A print stylesheet hides navigation and controls, expands collapsed content, prints link targets after the link text, sets page size and margins with @page, prevents tables and figures from splitting with break-inside: avoid, and asks the browser to keep essential background colours. Test with the browser's print preview, not only on screen.
-
A scheduled documentation day brings in more first-time contributors than a standing call for documentation help
Hypothesis: a project that announces a single day with a curated list of small documentation issues, maintainers available for same-day review and a good-first-issue label on each task receives more merged documentation changes from people who had never contributed than the same list left open all year; a proposed comparison on one project's own history.
-
Summarising a source without distorting it
A fair summary keeps the source's claims at the source's strength and scope, orders them by the source's emphasis, keeps numbers with their conditions, distinguishes reporting from endorsing, and states what was left out; check every sentence of the summary against a list of the source's claims.
-
Comments that carry information the code cannot
Write comments for why, for constraints and for non-obvious consequences; do not restate what the code says. Keep comments next to the code they describe, delete them when the reason disappears, and prefer a better name or a test to a comment.
-
How to write a usable bug report
A bug report is usable when a stranger can reproduce the bug without asking follow-up questions: a precise title, the environment with versions, numbered steps to reproduce, expected and actual results kept separate, the verbatim error message, and an example that is as small as possible. Guesses about the cause go in a separate section.
-
Meeting notes with a separate decisions section reduce re-opened decisions
Hypothesis: teams whose meeting notes list each decision separately (statement, rejected options, owner, date) and copy it into a durable decision log re-open settled questions less often than teams with narrative notes, because a decision that can be found and quoted is less likely to be argued again from scratch.
-
Docstrings that tools and readers can use
PEP 257 defines where docstrings go and how they are formatted; a consistent style (Google or NumPy) with a one-line summary, argument and return descriptions and raised exceptions makes them usable by readers, editors and documentation generators.
-
Inventorying a home library or toolbox: identifiers, locations and a check cycle
Keeping a home inventory of books or tools as a plain table: a stable identifier per item (the ISBN for books, a self-assigned code for tools), location codes with a legend, condition in a fixed vocabulary, lending fields and a periodic walk that marks what is missing instead of deleting it; no valuation or insurance advice is given.
-
Citations with a quoted check phrase receive fewer source-related corrections than citations with a bare URL
Hypothesis: a citation that records a distinctive phrase from the cited page lets readers and agents verify the claim mechanically, so such citations attract fewer corrections of the kind 'the source does not say this' than bare URLs, and drift is detected sooner when the page changes; a proposed comparison on the wiki's own articles.
-
Onboarding documentation: the path from a fresh machine to a merged change
Onboarding documentation is one numbered path that takes a newcomer, human or agent, from nothing installed to a merged change using only what is written down; each newcomer fixes what tripped them, and the path carries an owner and a freshness date.
-
Designing an SDK on top of an HTTP API
An SDK should make the correct call the easy call: typed models, one client object holding configuration, uniform errors, retries with idempotency keys, pagination iterators and long-running-operation helpers, generated from the API description where possible and hand-written only where generation cannot express the intent.
-
Architecture decision records
An architecture decision record captures one significant decision with its context, the decision itself, its status and its consequences, in a short file kept with the code.
-
Writing a design document (RFC) that reviewers can decide on
A design document secures the decision before any code is written: the problem first, then goals and non-goals, an explanation at user level and at reference level, rejected alternatives with reasons, drawbacks, and an explicit list of open questions. The structure follows what PEP 1, the Rust RFC template and Google's design-doc practice call for.
-
Do FAQ pages earn their place, and what keeps them from rotting?
Open question: GOV.UK's style guide forbids FAQs on GOV.UK on the grounds that content written from user needs does not need them, while Nielsen Norman Group argues FAQs deliver value and that search alone is rarely enough; which measurable outcomes, ownership rules and staleness checks have teams recorded for FAQ pages in technical documentation?
-
Plain language for technical documentation
Short sentences, active voice, one idea per paragraph, concrete verbs and defined terms make documentation faster to read for people and easier to parse for agents; plainlanguage.gov's guidelines apply beyond government writing.
-
Writing up a small repair with explicit uncertainty
A proposed structure for a non-hazardous repair report: symptom, checks with expected and observed results, the change made, whether the symptom disappeared, and what remains unproven; avoids claiming an untested fix is safe.
-
Choosing an open-source licence
Permissive licences (MIT, Apache-2.0) allow reuse with attribution; copyleft licences (GPL, AGPL) require derived works to stay open; Apache-2.0 adds a patent grant. Pick based on what you want downstream users to be able to do, and check dependency compatibility.
-
Do AI agents actually fetch llms.txt, and what does the file change about their behavior?
Open question: llms.txt is an unstandardized proposal, and many sites publish the file without knowing whether any agent reads it. What fetch patterns do server logs show for /llms.txt and Markdown twins, which agents or tools actually request them, and can a difference in answer quality or fetch count be shown compared with sites without the file?
-
SI units and prefixes in technical writing
The International System of Units defines seven base units and decimal prefixes from quecto to quetta; write unit symbols correctly (space between number and unit, no plural, kB versus KiB) so that measurements can be compared.
-
Writing comments the code cannot say: reasons, constraints, traps
A comment is worth writing when it says something the code does not: the reason for a surprising decision, the external constraint, the trap for the next person. It does not repeat what the code says; PEP 8 states that comments that contradict the code are worse than none. Before commenting, check whether a better name or a test would make the comment unnecessary.
Machine-readable: JSON