ドキュメント作成で意識しているポイントとフレームワークの活用
この記事は ミライトデザイン Advent Calendar 2024 の 6 日目の記事です。
前回は ucan さんの記事でした。
はじめに
皆さん、ドキュメントは書いてますか。
ドキュメント作成は、他の人と情報共有をするために必要となる大事なスキルです。
特に技術的な内容や複雑な情報を扱う場合、わかりやすく効果的なドキュメントが求められます。
自分自身、ドキュメントを書く際にはいくつかのポイントを意識しています。
この記事では、自分が実践しているドキュメント作成の意識しているポイントや、 Diátaxis ( ディアタクシス ) というフレームワークに基づいたドキュメントのカテゴリ分けについて紹介します。
ドキュメント作成時の意識すべきポイント
ドキュメントを書くうえでいくつか意識したり気をつけたりしているポイントがあるので紹介します。
テーマごとにドキュメントを分ける
異なるテーマやトピックに関する情報は、別々のドキュメントに分けることで、目的に応じた情報となり検索しやすくなります。
例えば、あるプロジェクトのドキュメントに、見出しで「手順」「使用方法」「トラブルシューティング」といった分け方をするのではなく、ドキュメント自体を分けることで特定の情報を探しやすくなります。
関連するドキュメントであれば、他のドキュメントをリンクさせることで、必要な情報に簡単にアクセスできます。
さらに、プロジェクトのドキュメントとしてまとめたいときは、テーマごとに分けたドキュメントのリンク集とすることで読み手にとって必要な情報にアクセスしやすくなります。
読み手視点で書く
ドキュメントは、誰が読むのかを常に意識して書くことが重要です。
読者が求めていることや背景を理解し、読み手にとってわかりやすい内容となることを意識します。
例えば、技術者向けのドキュメントと一般ユーザー向けのドキュメントでは、使用する用語や説明の詳細さが異なります。
技術者には専門用語を使っても理解されますが、一般ユーザーにはわかりやすい言葉で説明する必要があります。
また、読者のレベルに応じて、前提知識を明示することも大事です。
これは自分がより意識していることですが、ドキュメントを書いていると自分の前提知識と読者の前提知識が異なることはよくあります。
読者によっては「これはどういう意味か」「これはどういうことか」などの疑問が出るため、前提知識・前提情報の明示をアップデートするように意識しています。
Why を書く
ドキュメントには「何を (What)」「どうやって (How)」について書かれていることは多いですが、「なぜ (Why)」についてのは記載が少ないこともよくあります。
「読み手視点で書く」とも繋がりますが、「なぜ」を書くことでその背景や目的が伝わります。
わかりやすく簡潔に
情報を伝える際には、わかりやすく、簡潔に表現することが大切です。
冗長な表現を避けて、伝えたい要点を明確にすることで、読者が理解しやすくなります。
例えば、長い文章を短い段落に分けたり、箇条書きを使ったりすることで、視覚的にも情報が整理されて読みやすくなります。
また、図や表を記載することで、視覚的に情報を伝えることができ、よりわかりやすいドキュメントになります。
伝えたいものによっては文章より図や表などの視覚的な情報のほうがわかりやすいです。
1 文が長くならないようにする
長い文は読者にとって理解されづらいので、1 文に書く内容はできるだけ絞るようにします。
「〜ので」「〜おり」「〜が」「〜で」などのつなぎ言葉を増やしてしまうと、 1 文に複数の内容がつながってしまいます。
また、句点（、）を 1 文で多く使っている場合も文の内容を増やしてしまいます。
項目や手順などが多い場合は箇条書きを使用することでわかりやすい文になると思います。
曖昧な表現はやめて具体的に書く
曖昧な表現は誤解を招く可能性があります。具体的な言葉を使い、明確な情報を記載することが重要です。
例えば、「デプロイには時間がかかります」といった表現ではなく、「デプロイには 10 分ほどかかります」などのような具体的な数値やデータを記載します。
目的が明確なものは辞書形式で書く
辞書形式とは、何か特定の情報を調べるために読むことを想定したドキュメントです。
マニュアルや仕様書は、わからないことを調べたり、知りたい情報を得ることが目的です。
そのため、目的が明確なドキュメントは辞書形式で整理することで、読者が必要な情報へすぐアクセスできるようにします。
例えば、API 仕様書では、各エンドポイントの説明を見出しとして整理し、必要な情報をすぐに見つけられるようにします。
調査やチュートリアル系は読み物形式で書く
読み物形式とは、最初から流れに沿って読むことを想定したドキュメントです。
この形式は、特に報告書や説明書、チュートリアル、調査などに適しており、読者の目的が曖昧な場合でも、情報を段階的に得ることができます。
ドキュメントのカテゴリ分け
以前まではドキュメントのカテゴリを「情報」「環境」「資料」「メモ」など、いくつかの雑多なカテゴリで分けていました。
そのため、どのドキュメントがどのカテゴリにあるのかなどが曖昧になっており、ドキュメントの管理自体も雑多になってしまっていました。
そこで Diátaxis ( ディアタクシス ) フレームワークというものを知り、参考にして一部を取り入れてみました。
Diátaxis フレームワーク
Diátaxis フレームワークはドキュメントを 4 つのカテゴリに分け、それぞれがどのような内容で記述するかを整理するフレームワークです。
4 つの異なるニーズに合わせることで、整備がしやすく読者も読みやすい構成にすることが可能となります。
Diátaxis より引用
公式ドキュメント には詳細な記載があり、内容もそこまで多くないので一度目を通してみてもいいと思います。
-
Tutorial
- チュートリアルとして学ぶためのガイド。スタートガイドやスキル・知識のキャッチアップなど。
- 新しい人が学べるようにする学習指向のドキュメント。
-
How-to Guide
- ある問題や目的に対しての手順を表す。インストール手順や設定方法など。
- 特定の問題や目的を解決する目的指向のドキュメント。
-
Reference
- 情報などの記載がされているリファレンス。用語集や仕様書など。
- ある対象の知識を得るための情報指向のドキュメント。
-
Explanation
- 調査結果や分析、議論をまとめた背景や理解のための文書。調査メモや分析、議事録など
- 特定のトピックに対する背景や理由を知るための理解指向のドキュメント。
下記の記事も参考になるので見てみてください。
自分のドキュメントにおけるカテゴリ分けの実例
自分のドキュメントでは、上記のカテゴリを参考にし、各テーマに応じた情報を整理しています。
| タグ | 説明 |
|---|---|
Tutorials |
最初に読む |
How-to guides |
特定のタスクを解決する |
Reference |
参考情報や資料情報 |
Memo |
調査や分析、個人的なメモなど |
Explanation ではなく Memo とカテゴリ分けしたのは、内容が曖昧になりそうな Explanation では、何を記載すべきかが迷いやすいと判断したためです。
具体的な情報が求められる場合、読者が混乱する可能性もあるため、よりシンプルな Memo を選びました。
また、個人のメモでも調査内容や経緯がわかるものであれば、気軽に残しやすいと考えたためです。
このようにカテゴリ分けをすることで、読者は目的によって以下のようにカテゴリから情報を見つけることができるようになります。
- Join したばかりの人には
Tutorialsを読んでもらう - 何か解決したいことがあれば
How-to guidesから探してもらう - 何か情報を見つけたければ
Referenceから探してもらう - 過去の経緯や調査内容が知りたいときは
Memoを読んでもらう
実際には、Reference の中でもいろいろな分類にできそうな内容があったり、 Memo の中でも他カテゴリのドキュメントとして整理して残す必要があるなどの問題点はあります。
色々と検討余地はありますが、現時点ではこの方法で運用してみています。
まとめ
今回は、自分がドキュメント作成で意識しているポイントやフレームワークの活用方法について紹介しました。
これらの方法が、少しでも参考になれば嬉しいです。
もし他に良い知見やアイデアがあれば、ぜひコメントで教えていただけるとありがたいです。
次回
次回は mozumasu さんの「楽しいインフラエンジニア入門」についての記事となります。
Discussion