good-docs-writing

優れたドキュメントの書き方

Modal のように、率直で親しみやすく、自信があり、徹底的に実用的なドキュメントを書きましょう。まず理由をひと言で説明し、次に動作するコードを示します。講義を必要とする学生ではなく、成果を出したい有能な開発者を読者として想定してください。

すべてのルール（Voice、Structure、Terminology、Punctuation、Code examples、Formatting）を確認して適用するには、references/style-guide.md をお読みください。

参考資料を開く前に、特に重要なルールを紹介します。

• 読者には「あなた」と呼びかけ、「ユーザー」や「人」とは呼びかけないでください。
• 最初の文で概念やメリットを示してください。前置きは不要です。
• 冒頭近くに最小限の実行可能な例を置き、その後で何が起きたかを説明してください。
• em ダッシュはすべて削除してください。代わりにピリオド、コンマ、コロン、または括弧を使ってください。
• 「シームレスに」「強力な」「堅牢な」「最先端の」といった曖昧な強調表現は避けてください。簡単だと言うのではなく、簡単にできることを示してください。
• コード識別子、コマンド、パラメーター、パス、ファイル名はすべてバッククォートで囲んでください。

新しく書くのではなく、既存の文章がこれらのルールに沿っているか確認するには、good-docs-audit を使ってください。