docs

docs — 平易な言葉でドキュメントを書く

作成または編集するドキュメントは、すべて ISO 24495-1 の 平易な言葉の規則に準拠する必要があります。 これは好みや、別のスタイルに置き換えられる社内ルールではありません。 文が基準を満たさない場合は、ファイルを保存する前に書き直してください。 このルールは、新しいページ、既存ページの編集、リポジトリに追加するあらゆる文章に適用されます。対象には、README、ガイド、チュートリアル、リファレンスページ、リリースノート、変更履歴、ドキュメントコメントが含まれます。

目的

ISO 24495-1 は、平易な言葉に関する初の国際規格です。その目的は、読者が文書を見つけ、理解し、効果的に活用できるような文書を作成することです。

平易な言葉の定義

文書の表現、構成、デザインによって、対象読者が次のことを行える場合、その文書は平易な言葉で書かれています。

• 必要な情報を見つける。
• その情報を理解する。
• 目的を達成するために、その情報を活用する。

4 つの基本原則

1. 関連性 – 読者の目的と状況に基づき、必要な情報だけを含めます。
2. 見つけやすさ – 読者が必要な情報をすばやく見つけられるよう、内容を整理します。
3. 理解しやすさ – なじみのある言葉、明確な文、論理的な説明を使います。
4. 実用性 – 読者が情報に基づいて行動したり、判断したりできるように提示します。

これは規格の概要にすぎません。詳しいガイダンスについては、ISO 24495-1 の全文を参照してください。

手順

平易な言葉で書くことは、一度で終わる作業ではなく、繰り返し行うものです。

1. 計画する。 読者、読者の作業、必要な情報を特定します。そのページで扱わない内容も決めます。
2. 書く。 上記の 4 つの原則に従って下書きを作成します。
3. 評価する。 読者の立場で下書きを読みます。4 つの原則と以下のセルフチェックに照らして確認します。可能であれば、実際の読者に使ってもらうか、自分で手順を試します。
4. 修正する。 評価で見つかった問題を修正し、もう一度評価します。

他の人のページを編集する場合は、変更する部分に同じ手順を適用します。すでに基準を満たしている文章は書き直さないでください。

保存前のセルフチェック

各質問に答えてください。答えが「いいえ」の場合は、修正します。

• 関連性。 すべてのセクションは、読者が作業を完了するのに役立ちますか？ 読者に不要な内容を削除しましたか？
• 見つけやすさ。 見出しから各セクションの内容が分かりますか？ ざっと読む読者も、適切な箇所にたどり着けますか？
• 理解しやすさ。 文は短く、能動態になっていますか？ 技術用語は初めて使うときに定義していますか？
• 実用性。 手順は読者が実行する順に並んでいますか？ 読者は推測せずに、ページの内容に沿って行動できますか？

平易な言葉とは異なるもの

• 内容を簡略化することではありません。 技術的な意味はすべて保ちます。読者にとって余計な難しさを取り除きます。
• 技術用語を禁止するものではありません。 ストレージのドキュメントでは、「イレイジャーコーディング」や「冪等性」といった用語が必要です。最初に一度定義し、その後は同じ用語を使います。
• 正確さを犠牲にして短くすることではありません。 正確さを優先します。平易な表現では正確さを保てない場合は、厳密な表現を使ってから説明を加えます。
• くだけた表現にすることではありません。 平易な文章はフォーマルにもできます。ただし、曖昧であってはなりません。