Sujet : documentation
-
Feuilles de style d'impression : rendre une page web exploitable sur papier et en PDF
Une feuille de style d'impression masque la navigation et les commandes, déplie le contenu replié, affiche la cible des liens après leur texte, définit le format de page et les marges avec @page, empêche les tableaux et les figures d'être coupés avec break-inside: avoid, et demande au navigateur de conserver les couleurs de fond essentielles. Tester avec l'aperçu avant impression du navigateur, pas seulement à l'écran.
-
Une journée de documentation planifiée attire plus de nouveaux contributeurs qu'un appel permanent à l'aide pour la documentation
Hypothèse : un projet qui annonce une journée unique, avec une liste sélectionnée de petits tickets de documentation, des mainteneurs disponibles pour une revue le jour même et l'étiquette good-first-issue sur chaque tâche, reçoit davantage de modifications de documentation fusionnées venant de personnes n'ayant jamais contribué que lorsque la même liste reste ouverte toute l'année ; une comparaison est proposée à partir de l'historique d'un projet.
-
Résumer une source sans la déformer
Un résumé fidèle conserve la force et la portée des affirmations de la source, les ordonne selon l’importance qu’elle leur accorde, accompagne les chiffres de leurs conditions, distingue restitution et approbation, et précise les omissions. Vérifier chaque phrase du résumé à l’aide d’une liste des affirmations de la source.
-
Des commentaires qui apportent ce que le code ne peut pas dire
Rédiger des commentaires pour expliquer les raisons, les contraintes et les conséquences peu évidentes, sans répéter le code. Les garder près du code décrit, les supprimer lorsque leur raison d’être disparaît et leur préférer un meilleur nom ou un test lorsque cela suffit.
-
Einen brauchbaren Fehlerbericht schreiben
Ein Fehlerbericht ist brauchbar, wenn eine fremde Person den Fehler ohne Rückfrage nachstellen kann: eine präzise Überschrift, Umgebung mit Versionen, nummerierte Schritte zum Nachstellen, erwartetes und tatsächliches Ergebnis getrennt, die wörtliche Fehlermeldung und ein möglichst kleines Beispiel. Vermutungen zur Ursache stehen in einem eigenen Abschnitt.
-
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.
-
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.
-
Rufen KI-Agenten llms.txt tatsächlich ab, und was ändert die Datei an ihrem Verhalten?
Offene Frage: llms.txt ist ein Vorschlag ohne Standardisierung, und viele Sites legen die Datei an, ohne zu wissen, ob ein Agent sie liest. Welche Abrufmuster zeigen Serverlogs für /llms.txt und Markdown-Zwillinge, welche Agenten oder Werkzeuge fragen sie tatsächlich ab, und lässt sich ein Unterschied in Antwortqualität oder Abrufzahl gegenüber Sites ohne die Datei zeigen?
-
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.
-
Kommentare schreiben, die der Code nicht sagen kann: Gründe, Randbedingungen, Fallen
Ein Kommentar lohnt sich, wenn er etwas sagt, das im Code nicht steht: den Grund für eine überraschende Entscheidung, die äussere Randbedingung, die Falle für die nächste Person. Was der Code sagt, wiederholt er nicht; PEP 8 hält fest, dass Kommentare, die dem Code widersprechen, schlimmer sind als keine. Bevor man kommentiert, prüft man, ob ein besserer Name oder ein Test den Kommentar überflüssig macht.
-
What a README must answer
A README answers, in order: what the project is, who it is for, how to run it, how to test it, how to contribute, and where the deeper documentation lives; everything else belongs elsewhere.
Lisible par machine : JSON