皆さん、こんにちは!テクニカルライティングシリーズへようこそ。前回のレッスンでは明確さを大切にすることに焦点を当てましたが、今回はその親戚とも言える「一貫性」について話しましょう。
新しいソフトウェアのユーザーマニュアルを読んでいると想像してください。1ページ目では、クリックすべきボタンがOKと呼ばれています。3ページ目では、それが確認と呼ばれています。そして5ページ目では、ただの✓になっています。混乱しますよね?これは一貫性のなさの典型的な例であり、ユーザーに深刻なストレスを与える可能性があります。
技術文書における一貫性とは、単に正しい文法だけの話ではなく、予測可能性と信頼の問題です。ドキュメントに一貫性があれば、読者は何を期待すればよいかが分かります。用語を学び、意味を推測するために立ち止まる必要もなく、自信を持ってコンテンツをたどることができます。
ドキュメントにおいて一貫性が重要な理由
- 信頼を築く: ドキュメントに一貫性があると、製品がより専門的で洗練され、信頼できるものに見えます。
- 混乱を減らす: ユーザーは、異なる用語が同じ意味なのかどうかを考えるために時間を無駄にする必要がなくなります。
- ユーザー体験を向上させる: ドキュメントが読みやすく、追いやすくなり、ユーザーの体験がよりスムーズになります。
- 流し読みを助ける: 一貫した書式は、読者が探している情報をすばやく見つけるためにドキュメントをスキャンする助けになります。ほとんどの人はドキュメントを最初から最後まで読むのではなく、ざっと目を通して質問への答えを探しているだけです。
一貫性を支える柱
一貫性を、今すぐ意識できる4つの主要な領域に分けてみましょう。
- 文法とスペル
- 用語
- 書式
- トーンとボイス
1. 文法とスペル
文章の中で誤った単語(例えば「wear」なのか「where」「we're」「were」なのか)を使ってしまったとき、その違いに気づけるでしょうか?正しい文法とスペルを使うことは、ドキュメントを洗練された、きちんとした文章に見せるだけでなく、理解しやすくし、他言語への翻訳もしやすくします。AIによる要約やエージェントの利用が広がる中、正しい文法を確保することは、明確で効果的なコミュニケーションのために欠かせません。
スペルミスは、会社にとっても、書き手であるあなた自身にとっても、非常に恥ずかしいものになり得ます。そのため、優れたスペルチェッカーがある場合でも、必ず手動でスペルチェックを行いましょう。
ヒント: フォーマルなドキュメントだけでなく、日常の会話やメール、テキストメッセージの中でも文法を改善していくことが、文章力を高める最も効果的な方法です。
2. 用語
あるボタンをある場所で保存と呼ぶなら、技術文書のあらゆる場所で保存と呼びましょう。プロジェクトのための重要な用語や用語集の小さなリストを作成し、それを守りましょう。これには製品名、機能名、専門用語も含まれます。一夜にして巨大な用語集を作る必要はありません。まずは最も重要な用語から始めて、必要に応じて追加していけばよいのです。
3. 書式
コードをどのように強調しますか?コードブロックを使いますか?それとも別のフォントを使いますか?一度決めたら、それを守りましょう。UI要素には太字を使いますか?それはあなた次第ですが、すべてのドキュメントで一貫させましょう。これは見出し、箇条書き、番号付きリスト、さらには句読点の使い方にも当てはまります。
4. トーンとボイス
ボイスとは、ドキュメントの個性のことです。これはすべてのコンテンツを通じて一貫している必要があります。ボイスは明確で直接的、専門用語を避けるべきものです。一方トーンは、ドキュメントの種類によって変わることがあります。例えば、チュートリアルでは会話的なトーンが使われることがある一方、トラブルシューティングガイドではより直接的で落ち着いたトーンが使われることがあります。詳しくはGoogle開発者ドキュメントガイドをご覧ください。
実践的なヒント: スタイルガイドを作る
一貫性を確保する最良の方法は、チームや組織に適用できるシンプルなスタイルガイドを作ることです。あなたの会社には公開されているスタイルガイドはありますか?もしあれば、それを参考にするとよいでしょう。あるいは、オンラインで公開されている多くのスタイルガイドを利用することもできます。
会社やチーム特有のニュアンスは、スタイルガイドに文書化しておくべきです。100ページもある文書である必要はありません。重要な用語、書式のルール、好ましいトーンを記載した、シンプルな共有ドキュメントやNotionページで十分です。
例えば:
ヒント: もし技術文書にdocs-as-codeのアプローチを採用しているなら、さらに一歩進んで、このスタイルルールをリンターに追加することもできます。
明確さに焦点を当てることで、明確なだけでなく、信頼性が高くプロフェッショナルなドキュメントを作成する道を着実に歩んでいけるでしょう。テクニカルライティングの旅にぜひ頑張ってください。スタイルガイドにどんな項目を入れられるか考えて、今日から始めてみましょう!
他にどのような執筆関連のトピックに興味があるか、ぜひコメントで教えてください。