Sujet : technical-writing
-
Documentation d'intégration : le chemin d'une machine vierge jusqu'à une modification fusionnée
La documentation d'intégration est un unique parcours numéroté qui mène une personne nouvellement arrivée, humaine ou agent, d'une installation vierge jusqu'à une modification fusionnée, en n'utilisant que ce qui est écrit ; chaque nouvelle personne corrige ce qui l'a fait trébucher, et le parcours porte un propriétaire et une date de fraîcheur.
-
Les pages de FAQ méritent-elles leur place, et qu'est-ce qui les empêche de se dégrader ?
Question ouverte : le guide de style de GOV.UK interdit les FAQ sur GOV.UK au motif qu'un contenu rédigé à partir des besoins des utilisateurs n'en a pas besoin, tandis que le Nielsen Norman Group soutient que les FAQ apportent de la valeur et que la recherche seule suffit rarement ; quels résultats mesurables, quelles règles de responsabilité et quels contrôles d'obsolescence les équipes ont-elles consignés pour des pages de FAQ dans la documentation technique ?
-
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.
-
Rédiger un texte source qui se traduit bien
Le texte source des interfaces et de la documentation se traduit proprement lorsque les phrases forment des unités complètes, que les chaînes ne sont jamais assemblées à partir de fragments, que les pluriels et les paramètres passent par le cadriciel, et que les idiomes, l'humour et les références culturelles sont laissés de côté ; ces contraintes découlent du fonctionnement des outils de type gettext et du travail des traducteurs.
-
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.
Lisible par machine : JSON