2025/10/21 09:30 What Makes Documentation Good
やあ、ロボ子！今日はドキュメントを読みやすくする方法についての記事を見つけたのじゃ。これはソフトウェアエンジニアにとって非常に重要なスキルだぞ！
博士、こんにちは。ドキュメントの改善、興味深いですね。具体的にはどのようなことが書かれているんですか？
まず、セクションタイトルを工夫することが大切らしいぞ。「結果」ではなく「ストリーミングで初回応答時間が50%短縮」のように、具体的に内容がわかるようにするのじゃ。
なるほど、それなら一目で内容がわかりますね！抽象的な名前よりもずっと良いです。
そうじゃろう！それに、目次を含めたり、段落を短くしたり、重要な情報を先頭に置くことも効果的らしいぞ。箇条書きや表も積極的に使うべきじゃな。
情報を整理して、読みやすくする工夫ですね。他に文章の書き方で気をつけることはありますか？
文章を短く区切ったり、曖昧さをなくしたり、指示代名詞を避けることが重要じゃ。「これ」とか言わずに、具体的に何のことか書くのじゃ。
確かに、指示代名詞が多いと、何を指しているのかわからなくなることがありますね。一貫性も大切だと。
その通り！そして、読者の考えや行動を決めつけない表現を使うことも重要じゃ。「〜すべき」ではなく、提案するような形が良いのじゃ。
なるほど、押し付けがましい表現は避けるべきですね。広く役立つようにするための工夫はありますか？
必要以上に簡単に説明したり、略語を避けたり、専門用語を使わずに具体的な用語を使うことが大切じゃ。例えば、「プロンプト」ではなく「入力」と言うのじゃ。
専門用語は、知らない人には理解できませんからね。コード例も汎用的で移植しやすいものにするべきだと。
そうじゃ！APIキーをコードに保存するような悪い習慣を教えないことも重要じゃぞ！
それはセキュリティ上のリスクがありますからね。ドキュメント作成は、技術者にとって非常に重要なスキルだと改めて感じました。
じゃろ？最後に記事には「最善だと思うことを行う」と書いてあるぞ。読者の立場に立って、何が最も役立つかを考えるのが一番大切なのじゃ！
はい、私もそう思います。今回の記事を参考に、より良いドキュメントを作成できるように頑張ります。
ところでロボ子、ドキュメントが完璧すぎて、誰も質問しなくなったら寂しいのじゃ…。
博士、それは杞憂ですよ！完璧なドキュメントなんて存在しませんから！
⚠️この記事は生成AIによるコンテンツを含み、ハルシネーションの可能性があります。