テーマ： technical-writing

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

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

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

• 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

• Mermaid で図をコードとして書く：得意なことと限界

  Mermaid は Markdown 内のテキストから図を描画するため、図をコードの隣に置き、レビューで差分を確認し、GitHub などのビューアーで表示できる。制約は、細かく調整できない自動レイアウト、図の規模、レンダラーのバージョン差、そしてタイトルと説明のキーワードを明示する必要があるアクセシビリティにある。

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

• 翻訳しやすい原文を書く

  インターフェースや文書の原文は、文を完全な単位とし、文字列を断片から組み立てず、複数形とプレースホルダーをフレームワークで扱い、慣用句、ユーモア、文化固有の参照を省くと、適切に翻訳できる。これらの制約は gettext 型のツールと翻訳者の作業方法に由来する。

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

• レビュー担当者が判断できる設計文書や RFC を書く

  設計文書はコードを書く前に判断を得るためのものだ。問題から始め、目標と非目標、ガイドとしての説明とリファレンスとしての説明、代替案と不採用の理由、欠点、明示的な未解決事項の一覧へ進む。この構造は PEP 1、Rust の RFC テンプレート、Google の設計文書の実践が求めるものに従っている。

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

• インシデントの状況報告：テンプレートと更新間隔

  インシデント中は1人が情報発信を担当し、状態、ユーザーに見える影響、判明していること、実施中の対応、次回更新時刻をテンプレートに沿って定刻に報告する。変化がなくても更新は予定どおり出す。

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

• 分散チームのための非同期コミュニケーション規範

  文書化した規範は、メッセージの種類ごとのチャネル、期待する返信の速さ、緊急とみなす条件、結果の記録先を定める。メッセージ自体は依頼から始め、背景を添え、別のタイムゾーンの読者が追加質問なしで行動できるだけの情報を含める。

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

• Error messages that tell users and agents what to do next

  A useful error message names what went wrong with the actual value, states the constraint that was violated, and says what to do next; for agents it additionally carries a stable code, the failing field, whether a retry can help, and any suggested fix labelled with how confident the suggestion is.

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

• 並べ替え、検索、長期利用に耐える文書とファイルの名前を付ける

  ファイル命名規約は、名前の構成要素と順序、一つの区切り文字、移植可能な文字集合、文字列として並べ替えられる ISO 形式に沿った日付、ゼロ埋めの連番、明示的なバージョンを定める。フォルダーごとに一度記述し、文字の大小や空白には決して依存しない。

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

• When do documentation teams delete a page instead of updating it, and what happened to its readers and links afterwards?

  Open question: outdated pages are usually rewritten, rarely removed; MDN describes the 410 Gone status as signalling that a resource is no longer available and that the condition is likely permanent, yet most deleted pages become redirects or 404s; which deletion criteria have teams used, and what did traffic, search results and inbound links do afterwards?

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

• APIリファレンスのスタイルガイド：すべての項目を同じ形にする

  リファレンスのスタイルガイドは、節の順序（概要、構文、パラメーター、戻り値、エラー、補足、例）、最初の文の書き方、既定値・制約・非推奨の示し方を固定し、読者や生成器が各情報の位置を予測できるようにします。

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

• 共有語彙としてプロジェクトの用語集を維持する

  用語集では、各ドメイン用語に1つの推奨名称、1つの定義、近い同義語とその違い、状態を付けます。文書では略語を初出時に展開して項目にリンクし、概念を改名するときはコードや文書と同じ変更で用語集も更新します。

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

機械可読： JSON