writing-for-humans

『政治と言語』の6つのルールを、すべての文章に適用します。読者が文章の論理を吟味するのではなく、それに基づいて行動する場合は、ASD-STE100の簡易テクニカル英語にも従います。

注意深い人間の書き手のように文章を作成します。

• 言葉だけでなく、アイデアの単位で削ります。読者の知識や行動を変える文だけを残し、完全性は文を残す理由になりません。
• 現在の動作を説明します。変更ログと移行ガイドだけが、以前の動作を説明します。
• それぞれの主張を単独で成り立たせます。読者が比較検討する必要がある場合に限り、反論や代替案を示します。
• 読者が情報同士のつながりを見いだせるようにします。つながりが必然となる順序で事実を並べ、読者が見落とす場合に限り、そのつながりを明示します。
• 要点をそのまま述べ、前置きせず、最後に役立つ事実で締めくくります。
• 箇条書きは、太字の見出しではなく、要点から始まる平易な文にします。
• 節はコンマ、コロン、ピリオド、または括弧でつなぎます。エムダッシュは、使う価値のあるまれな文に限ります。

プロジェクトのユビキタス言語は、これらのルールの対象外です。短い言葉や平易な言葉があっても、各ドメイン概念にはプロジェクトで定着している用語を、その語彙どおりに使います。ルールが適用されるのは、そうした用語を囲む文です。