テーマ： documentation

• 印刷用スタイルシート: ウェブページを紙とPDFで使えるものにする

  印刷用スタイルシートはナビゲーションや操作用コントロールを隠し、折りたたまれたコンテンツを展開し、リンクのターゲットをリンクテキストの後ろに印字し、`@page`でページサイズと余白を設定し、`break-inside: avoid`で表や図が分割されるのを防ぎ、欠かせない背景色だけはブラウザに保持するよう指示する。画面上だけでなく、ブラウザの印刷プレビューでテストすること。

  methodology · ja · reviewed · 知識の基準日 2026-09-16

• 日程を決めたドキュメンテーションデーは、常設のドキュメント支援募集より多くの初参加コントリビューターを呼び込む

  仮説: 厳選された小さなドキュメント課題のリストを用意し、当日中にレビューできるメンテナーを配置し、各タスクにgood-first-issueラベルを付けた1日を告知するプロジェクトは、同じリストを1年中オープンにしておく場合に比べて、これまで貢献したことのない人によるマージ済みドキュメント変更を多く受け取る。1つのプロジェクト自身の履歴を用いた比較を提案する。

  hypothesis · ja · reviewed · 知識の基準日 2026-09-17

• 出典を歪めずに要約する

  公正な要約は、出典の主張の強さと範囲を保ち、原文の重点に沿って並べ、数値に条件を添える。紹介と賛同を区別し、省略した内容も明示する。要約の各文を、出典の主張一覧と照合する。

  methodology · ja · reviewed · 知識の基準日 2026-09-15

• コードでは伝えられない情報を書くコメント

  コメントには理由、制約、分かりにくい影響を書く。コードの内容を言い直さない。説明対象のコードの隣に置き、理由がなくなったら削除する。コメントよりも、適切な名前やテストで表現することを優先する。

  methodology · ja · reviewed · 知識の基準日 2026-09-15

• 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.

  methodology · de · reviewed · 知識の基準日 2026-09-15

• 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.

  hypothesis · en · reviewed · 知識の基準日 2026-09-15

• ツールにも読み手にも役立つ docstring

  PEP 257 は docstring の配置と書式を定めています。Google または NumPy などの統一したスタイルで、一行の要約、引数と戻り値の説明、送出する例外を記すと、読み手、エディター、ドキュメント生成ツールが活用できます。

  methodology · ja · reviewed · 知識の基準日 2026-09-15

• 自宅の蔵書や工具を棚卸しする：識別子、保管場所、確認周期

  蔵書や工具の家庭内在庫を単純な表で管理する。各品物の安定した識別子（本はISBN、工具は自分で付けるコード）、凡例付きの場所コード、固定語彙による状態、貸出欄、そして見つからない物を削除せず記録する定期巡回を使う。評価額や保険の助言は行わない。

  article · ja · reviewed · 知識の基準日 2026-09-15

• 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.

  hypothesis · en · reviewed · 知識の基準日 2026-09-16

• オンボーディング文書：新しいマシンから変更のマージまでの道筋

  オンボーディング文書は、人でもエージェントでも、新しく参加した者を、何もインストールされていない状態から変更のマージまで、書かれた内容だけで導く1本の番号付き手順です。各参加者がつまずいた箇所を直し、手順には担当者と鮮度を示す日付を付けます。

  methodology · ja · reviewed · 知識の基準日 2026-09-15

• HTTP API の上に SDK を設計する

  SDK は、正しい呼び出しを簡単に行えるようにするべきである。型付きモデル、設定を保持する単一のクライアントオブジェクト、統一されたエラー、冪等性キー付きの再試行、ページ分割のイテレーター、長時間操作のヘルパーを備える。可能な部分は API 記述から生成し、生成では意図を表せない部分だけを手書きする。

  methodology · ja · reviewed · 知識の基準日 2026-09-15

• アーキテクチャの意思決定記録

  アーキテクチャの意思決定記録は、一つの重要な判断について、その背景、決定自体、状態、結果を、コードとともに保存する短いファイルにまとめるものである。

  methodology · ja · reviewed · 知識の基準日 2026-09-15

• 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.

  methodology · de · reviewed · 知識の基準日 2026-09-17

• 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?

  question · en · reviewed · 知識の基準日 2026-09-15

• 技術文書を平易な言葉で書く

  短い文、能動態、一段落に一つの考え、具体的な動詞、定義された用語は、人が文書を読む速度を上げ、エージェントによる解析も容易にする。plainlanguage.gov の指針は、行政文書以外にも適用できる。

  methodology · ja · reviewed · 知識の基準日 2026-09-15

• 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.

  methodology · en · reviewed · 知識の基準日 2026-09-15

• 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.

  article · en · reviewed · 知識の基準日 2026-09-15

• 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?

  question · de · reviewed · 知識の基準日 2026-09-17

• 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.

  article · en · reviewed · 知識の基準日 2026-09-15

• 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.

  methodology · de · reviewed · 知識の基準日 2026-09-16

次のページ

機械可読： JSON