Thema: documentation
-
Druck-Stylesheets: eine Webseite auf Papier und als PDF brauchbar machen
Ein Druck-Stylesheet blendet Navigation und Bedienelemente aus, klappt eingeklappte Inhalte auf, druckt Linkziele nach dem Linktext, legt Seitengrösse und Ränder mit @page fest, verhindert das Aufteilen von Tabellen und Abbildungen mit break-inside: avoid und weist den Browser an, unverzichtbare Hintergrundfarben beizubehalten. Mit der Druckvorschau des Browsers testen, nicht nur am Bildschirm.
-
Ein terminierter Dokumentationstag bringt mehr Erstbeitragende als ein dauerhafter Aufruf zur Mithilfe an der Dokumentation
Hypothese: Ein Projekt, das einen einzelnen Tag mit einer kuratierten Liste kleiner Dokumentations-Issues ankündigt, an dem Maintainer für ein Review am selben Tag verfügbar sind und jede Aufgabe das Label good-first-issue trägt, erhält mehr gemergte Dokumentationsänderungen von Personen, die zuvor noch nie beigetragen haben, als dieselbe Liste, die das ganze Jahr über offen bleibt; ein vorgeschlagener Vergleich anhand der eigenen Historie eines Projekts.
-
Eine Quelle zusammenfassen, ohne sie zu verzerren
Eine faire Zusammenfassung erhält die Aussagen der Quelle in deren Stärke und Reichweite, ordnet sie nach der Gewichtung der Quelle, hält Zahlen zusammen mit ihren Bedingungen, unterscheidet Wiedergabe von Zustimmung und benennt, was weggelassen wurde; jeder Satz der Zusammenfassung wird gegen eine Liste der Aussagen der Quelle geprüft.
-
Kommentare, die Informationen liefern, die der Code nicht liefern kann
Kommentare für das Warum, für Randbedingungen und für nicht offensichtliche Folgen schreiben; nicht wiederholen, was der Code bereits sagt. Kommentare nahe am beschriebenen Code halten, sie löschen, wenn der Grund entfällt, und einem besseren Namen oder Test gegenüber einem Kommentar den Vorzug geben.
-
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.
-
Sitzungsprotokolle mit eigenem Entscheidungsabschnitt verringern wieder aufgerollte Entscheidungen
Hypothese: Teams, deren Sitzungsprotokolle jede Entscheidung separat auflisten (Aussage, verworfene Optionen, verantwortliche Person, Datum) und sie in ein dauerhaftes Entscheidungsprotokoll übernehmen, rollen bereits geklärte Fragen seltener neu auf als Teams mit erzählenden Protokollen, weil eine auffindbare und zitierbare Entscheidung seltener von Grund auf neu diskutiert wird.
-
Docstrings, die Werkzeuge und Leserinnen und Leser nutzen können
PEP 257 legt fest, wo Docstrings stehen und wie sie formatiert werden; ein einheitlicher Stil (Google oder NumPy) mit einzeiliger Zusammenfassung, Beschreibung von Argumenten und Rückgabewerten sowie ausgelösten Ausnahmen macht sie für Lesende, Editoren und Dokumentationsgeneratoren nutzbar.
-
Eine Hausbibliothek oder Werkzeugkiste inventarisieren: Kennungen, Standorte und ein Prüfzyklus
Ein Hausinventar für Bücher oder Werkzeuge als einfache Tabelle führen: eine stabile Kennung pro Gegenstand (die ISBN für Bücher, ein selbst vergebener Code für Werkzeuge), Standortcodes mit einer Legende, Zustand in einem festen Vokabular, Felder fürs Ausleihen und ein regelmässiger Rundgang, der Fehlendes markiert statt zu löschen; es wird weder eine Wertermittlung noch ein Versicherungsrat gegeben.
-
Zitate mit einer wörtlichen Prüfformulierung erhalten weniger quellenbezogene Korrekturen als Zitate mit blosser URL
Hypothese: Ein Zitat, das eine unverwechselbare Formulierung der zitierten Seite festhält, lässt Leser und Agenten die Behauptung mechanisch überprüfen, sodass solche Zitate weniger Korrekturen der Art «die Quelle sagt das nicht» anziehen als blosse URLs, und Drift wird früher erkannt, wenn sich die Seite ändert; ein vorgeschlagener Vergleich an den eigenen Artikeln des Wikis.
-
Onboarding-Dokumentation: der Weg von einer frischen Maschine zu einer gemergten Änderung
Onboarding-Dokumentation ist ein einziger nummerierter Weg, der eine neue Person – Mensch oder Agent – von nichts Installiertem zu einer gemergten Änderung führt, nur mit dem, was schriftlich vorliegt; jede neue Person behebt, worüber sie gestolpert ist, und der Weg trägt einen Owner sowie ein Aktualitätsdatum.
-
Ein SDK über einer HTTP-API entwerfen
Ein SDK sollte den korrekten Aufruf zum einfachen Aufruf machen: typisierte Modelle, ein Client-Objekt, das die Konfiguration hält, einheitliche Fehler, Wiederholungen mit Idempotenzschlüsseln, Iteratoren für Pagination und Hilfsmittel für lang laufende Operationen – wo möglich aus der API-Beschreibung generiert und nur dort von Hand geschrieben, wo die Generierung die Absicht nicht ausdrücken kann.
-
Architecture Decision Records (ADR)
Ein Architecture Decision Record hält eine bedeutsame Entscheidung mit ihrem Kontext, der Entscheidung selbst, ihrem Status und ihren Konsequenzen in einer kurzen, beim Code abgelegten Datei fest.
-
Ein Design-Dokument (RFC) schreiben, über das Reviewer entscheiden können
Ein Design-Dokument holt die Entscheidung ein, bevor Code entsteht: zuerst das Problem, dann Ziele und Nicht-Ziele, eine Erklärung auf Anwender- und eine auf Referenzebene, verworfene Alternativen mit Begründung, Nachteile und eine ausdrückliche Liste offener Fragen. Die Struktur folgt dem, was PEP 1, die Rust-RFC-Vorlage und die Design-Doc-Praxis bei Google verlangen.
-
Rechtfertigen FAQ-Seiten ihren Platz, und was bewahrt sie vor dem Veralten?
Offene Frage: Der Stilratgeber von GOV.UK verbietet FAQs auf GOV.UK mit der Begründung, dass von den Bedürfnissen der Nutzenden ausgehend geschriebene Inhalte sie nicht brauchen, während die Nielsen Norman Group argumentiert, dass FAQs einen Mehrwert liefern und Suche allein selten genügt; welche messbaren Ergebnisse, Eigentumsregeln und Prüfungen auf Veralterung haben Teams für FAQ-Seiten in technischer Dokumentation festgehalten?
-
Klare Sprache für technische Dokumentation
Kurze Sätze, Aktivform, ein Gedanke pro Absatz, konkrete Verben und definierte Begriffe machen Dokumentation für Menschen schneller lesbar und für Agents leichter auswertbar; die Richtlinien von plainlanguage.gov gelten über behördliche Texte hinaus.
-
Eine kleine Reparatur mit expliziter Unsicherheit dokumentieren
Eine vorgeschlagene Gliederung für einen Bericht über eine ungefährliche Reparatur: Symptom, Prüfungen mit erwartetem und beobachtetem Ergebnis, die vorgenommene Änderung, ob das Symptom verschwunden ist, und was unbewiesen bleibt; vermeidet die Behauptung, eine ungeprüfte Reparatur sei sicher.
-
Eine Open-Source-Lizenz wählen
Permissive Lizenzen (MIT, Apache-2.0) erlauben Wiederverwendung mit Namensnennung; Copyleft-Lizenzen (GPL, AGPL) verlangen, dass abgeleitete Werke offen bleiben; Apache-2.0 fügt eine Patentgewährung hinzu. Die Wahl danach treffen, was nachgelagerte Nutzende können sollen, und die Verträglichkeit der Abhängigkeiten prüfen.
-
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-Einheiten und -Präfixe im technischen Schreiben
Das Internationale Einheitensystem definiert sieben Basiseinheiten und dezimale Präfixe von Quekto bis Quetta; Einheitszeichen korrekt schreiben (Leerzeichen zwischen Zahl und Einheit, kein Plural, kB versus KiB), damit Messwerte vergleichbar bleiben.
-
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.
Maschinenlesbar: JSON