Тема: technical-writing
-
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.
-
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?
-
Diagrams as code with Mermaid: what it does well and where it stops
Mermaid renders diagrams from text inside Markdown, so diagrams live next to the code, diff in review and are rendered by GitHub and other viewers; its limits are automatic layout you cannot fine-tune, size, renderer version differences and accessibility, which needs explicit title and description keywords.
-
Writing source text that translates well
Source text for interfaces and documentation translates cleanly when sentences are complete units, strings are never assembled from fragments, plurals and placeholders go through the framework, and idioms, humour and culture-specific references are left out; the constraints come from how gettext-style tools and translators work.
-
Writing a design document or RFC that reviewers can decide on
A design document earns a decision before code is written: problem first, then goals and non-goals, a guide-level and a reference-level explanation, alternatives with the reasons they were rejected, drawbacks, and an explicit list of unresolved questions; the structure follows what PEP 1, the Rust RFC template and Google's design-doc practice ask for.
-
Incident status updates: a template and a cadence
During an incident one person owns communication and posts updates on a fixed schedule from a template: status, user-visible impact, what is known, what is being done, and the time of the next update; the update goes out on time even when nothing has changed.
-
Asynchronous communication norms for distributed teams
Written norms say which channel carries which kind of message, how fast a reply is expected, what counts as urgent, and where outcomes are recorded; the message itself leads with the ask, carries its context, and is complete enough that a reader in another time zone can act without a follow-up question.
-
Error messages that tell users and agents what to do next
A useful error message names what went wrong with the actual value, states the constraint that was violated, and says what to do next; for agents it additionally carries a stable code, the failing field, whether a retry can help, and any suggested fix labelled with how confident the suggestion is.
-
Naming documents and files so that they sort, search and survive
A file-naming convention fixes the components of a name and their order, one separator, the portable character set, an ISO-style date that sorts as text, zero-padded sequence numbers and explicit versions; it is written down once per folder and never relies on letter case or spaces.
-
When do documentation teams delete a page instead of updating it, and what happened to its readers and links afterwards?
Open question: outdated pages are usually rewritten, rarely removed; MDN describes the 410 Gone status as signalling that a resource is no longer available and that the condition is likely permanent, yet most deleted pages become redirects or 404s; which deletion criteria have teams used, and what did traffic, search results and inbound links do afterwards?
-
An API reference style guide: one shape for every entry
A reference style guide fixes the order of sections (summary, syntax, parameters, return value, errors, remarks, example), the wording of the first sentence, and how defaults, constraints and deprecations are stated, so that readers and generators can predict where each fact is.
-
Maintaining a project glossary as the shared vocabulary
A glossary gives each domain term one preferred name, one definition, its near-synonyms and their differences, and a status; documents expand abbreviations on first use and link to the entry, and renaming a concept updates the glossary in the same change as the code and docs.
Машиночитаемо: JSON