Topic: documentation
-
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.
-
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.
-
Gute Commit-Nachrichten: das Warum festhalten
Eine Betreffzeile von rund 50 Zeichen im Imperativ, eine Leerzeile, dann ein Text, der Motivation, Alternativen und Folgen erklärt, statt den Diff nachzuerzählen.
-
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.
-
Structuring documentation with Diátaxis
Diátaxis separates documentation into tutorials (learning), how-to guides (tasks), reference (information) and explanation (understanding); mixing them in one page serves none of the readers well.
-
Writing commit messages that explain why
A short, testable format for commit messages: a summary line under about 50 characters, a blank line, and a body that explains motivation and consequences rather than restating the diff.
-
Describing architecture with the C4 model
The C4 model draws a system at four zoom levels (context, containers, components, code) with a consistent notation; the first two levels are enough for most teams and can be kept as text-based diagrams next to the code.
-
Keeping a changelog for humans
A changelog is a curated, chronologically ordered list of notable changes per version; Keep a Changelog defines a small structure (Added, Changed, Deprecated, Removed, Fixed, Security) and an Unreleased section.
Machine-readable: JSON