improve-writing

文章の改善

より質の高い文章を作成するための指針です。

ガイダンス

• 正式で中立的かつ専門的な言葉遣い： 色彩豊かな表現や比喩表現は避けてください。簡潔で事実に即したドキュメントを作成します。読者を楽しませる必要はありません。口語表現は避けてください。
• ダッシュやセミコロン、コロンは避ける： ダッシュやセミコロン、コロンを使わずに済むよう、直接的で能動的な表現を使ってください。並列的な文体、接続詞を省略した構文、括弧を使った構文、同格の構文は避けてください。
• リスト項目の後のコロン： リスト項目に強調された「見出し」の語句がある場合は、ピリオドではなくコロンを付けてください。以下のリストを例にしてください。
• 箇条書きは避ける： 集合の要素を列挙する場合など、箇条書きが適切なときに限って使用してください。段落でも構成できる文章を整理するための一般的な手段として使わないでください。
• 強調は意図的に使う： ドキュメント内で読者を案内するために、太字や斜体を使ってください。強調したテキストは、ページを素早く見渡すときの目印になります。ナビゲーションや概要把握において重要な役割を果たします。
• まず平易な言葉を使う： 特定の技術用語のほうが正確で、その正確さが文脈上重要な場合を除き、簡単な言葉を使ってください。たとえば、より簡単な動詞では伝わらない情報がある場合を除き、dispatch ではなく Send を使ってください。
• 装飾を避ける： 関連する意味を付け加えない装飾的な表現は省いてください。たとえば、orchestration、pipeline、synergy、first-class、platform-grade などの語句です。
• 技術用語は飾りではなく、正確に使う： Contract、boundary、observer、layer、primitive、interface は、それぞれ特定のエンジニアリング上の意味を持ちます。意図する意味と完全に一致する場合に限って使ってください。平易な言葉で表現できる場合は、そちらを優先してください。
• 技術用語をむやみに並べない： 色を添える目的だけで、かっこよく聞こえる言葉を使わないでください。ほかの簡単な表現では伝えられない意味を持つ用語は使い、そうでない場合は省いてください。
• 用語を統一する： ドキュメントで対象の名称を一度定義したら、後から同義語に置き換えないでください。定義した用語か、可能な限り平易な別の表現を使い、ドキュメント内で新しい同義語を作らないでください。
• 能動態を使い、動作する対象を先に置く： サブスクリプションのプランが変わると、サブスクリプションがイベントを発行します は、サブスクリプションのプラン変更イベントが発生すると、システムによってイベントが発行されます よりも適切です。動作するものを主語にしてください。
• 事実を述べるときに曖昧な表現を使わない： might、could、generally、typically などの表現は避けてください。不確かな内容は「未解決の質問」に記載するか、不確かであることを明示してください。事実であれば、明確に述べてください。
• 適切な場合にのみセクションを設ける： テキストの領域が互いに独立している場合に限り、セクション --- を使ってください。見出しで十分に構成できる場合に、文章を整理する手段として使わないでください。
• 正確さ： 正確さは最も重要です。具体的な名称を使う場合、特にコード表記（examble）を使う場合は、その名称をソースコードと完全に一致させてください。単純化してはいけません。名称を変更すると、該当する具体的な要素を特定できなくなるためです。