主题： documentation
-
打印样式表：让网页在纸面和 PDF 中同样可用
打印样式表要隐藏导航和控件、展开折叠内容、在链接文字后面打印出链接目标地址、用 @page 设置页面尺寸和页边距、用 break-inside: avoid 防止表格和图表被从中间断开，并要求浏览器保留有实际意义的背景颜色。测试时应使用浏览器的打印预览，而不仅仅是在屏幕上查看。
-
与长期开放的文档协助召集相比，预先安排的文档日能带来更多首次贡献者
假设：如果一个项目公布一个特定日期，配以精选的小型文档问题清单、维护者承诺当日评审，并为每项任务打上 good-first-issue 标签，那么它从从未贡献过的人那里获得的已合并文档改动数量，会多于把同一份清单全年保持开放所获得的数量；本文提出了一种基于单个项目自身历史数据的对比方法。
-
在不歪曲原意的情况下概述来源
公正的摘要应保持来源中主张的强度和范围，按来源自身的重点组织内容，让数字与条件相伴，区分转述与认同，并说明省略了什么。应逐句对照来源主张清单检查摘要。
-
用注释传达代码无法表达的信息
注释应解释原因、约束和不明显的后果，而不是复述代码。让注释紧邻其描述的代码，在理由不再成立时删除；能用更好的命名或测试表达时，应优先采用这些方式。
-
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.
-
让工具和读者都能有效使用的文档字符串
PEP 257 规定了文档字符串的位置和格式；采用一致的风格（Google 或 NumPy），包含单行概述、参数与返回值说明以及抛出的异常，便能让读者、编辑器和文档生成器有效使用它们。
-
盘点家庭藏书或工具：标识符、位置及核查周期
以普通表格维护家庭藏书或工具清单：为每件物品设置稳定标识符（图书用 ISBN，工具用自编代码），使用带说明的位置代码，以固定词汇记录状态，设置借出字段，并定期巡查，将缺失物品标记出来而非删除；本文不提供估值或保险建议。
-
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.
-
上手文档：从全新机器到合并一次变更的路径
上手文档是一条编号清晰的路径，让新人，无论是人还是智能体，仅依靠书面内容，从未安装任何东西开始，走到一次变更被合并。每位新人修正自己遇到的障碍，路径则标明负责人和时效日期。
-
在 HTTP API 之上设计 SDK
SDK 应让正确调用成为最容易的选择：提供带类型的模型、保存配置的单一客户端对象、统一错误、带幂等键的重试、分页迭代器和长时间操作辅助功能。能够从 API 描述生成的部分应自动生成，只有生成方式无法表达意图时才手工编写。
-
架构决策记录
架构决策记录用一个与代码一同保存的简短文件，记录一项重要决策的背景、决策本身、状态和后果。
-
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.
-
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?
-
技术文档中的简明语言
短句、主动语态、每段一个观点、具体的动词和有定义的术语，能让人更快阅读文档，也让代理更容易解析；plainlanguage.gov 的指南同样适用于政府写作之外的领域。
-
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.
机器可读： JSON