📑

わかりやすいドキュメントを書くために意識していること

2022/05/21に公開

目指しているドキュメント

この2つを意識している。

たくさんの情報をならべて「必要なことは全部書いたよ。ここから読み取ってね」じゃなくて、「必要な情報だけ」を「理解しやすい言葉えらびと構成」で届けたい。

漢字(特に画数の多い漢字)が続くと読み辛い。ひらがなばかりだと、もじのさかいめがよみとりにくい。

多義語(対応、かける、make)や代名詞(あれ、その、前者)など「読んでから意味を理解するまでにひと手間かかる表現」をなるべく減らす。

文章より図や動画の方がわかりやすい場合はどんどん使う。
縦長の図が多いとうるさくなりがちだから、図はできるだけ横長にできるよう調整する。
キャプチャを取るときは、CleanShotというツールが便利。

箇条書きを使ったり、コードで表現したり方がわかりやすい場合も多い。
エンジニア向けの手順書だと、日本語じゃなくてlinuxコマンドで書いた方がわかりやすくなることが結構ある。

h1(#)>h2(##)>h3(###)と順番に使うと、文字や余白が大きすぎたり、(見出しごとのスタイルの違いが少なくて)文章構造が掴みづらくなったりしがち。

サービスごとに使う見出しを調整している。Zennで書く場合は、大見出しにh1(#)、小見出しにh3(###)を使うのが良さそう。見出しが足りなくなったときは、太字を使うか、文章の構造を見直す。

専門用語をどこまで使うか、どれだけ詳しく説明するかなど、想定読者の立場から考える。
わかりにくいドキュメントの多くは「自分が理解できるからこれでいいや」から生まれている気がする。