はじめに

ソフトウェアを開発するとそのマニュアルを書く必要があります
で、このマニュアルのレビューでよくある指摘が「わかりづらい」

この指摘、(僕もよく言っちゃうけど)イラっとしますよね。「わかりづらい」って指摘がわかりづらい😡
この「わかりづらい」問題を回避するために、このページでは以下の点を考察します

マニュアルが「わかりづらい」ってなんだよ
どうやったら「わかりやすい」マニュアルになるのか

参考になるかもしれん資料

日本語の作文技術
- 内容はわかりやすい。単文をわかりやすく書くのに役立つ
理科系の作文技術
- 正直少ししか読んでない。先輩が「この本いい」って言ってた
Technical Writing | Google Developers
- 主に単文を分かりやすく書くことフォーカス。一部ドキュメントの構造に言及
Technical Writing Process
- Kingle Unlimitedで読める
- ドキュメントの構造について、Structureの章で述べている
- ドキュメントの種類ごとにどういう構造になるべきかを述べているので、結構いい

マニュアルが「わかりづらい」ってなんだよ

「わかりづらい」を具体化する

「わかりづらい」「わかりやすい」って言葉はいったん捨てます。だって意味わからんし

マニュアルを含め、全ての成果物はそのユーザーの要求を満たすならOKです
つまり、「わかりづらい」 は 「ユーザーの要求を満たさない」 ことを指摘しています

マニュアルのユーザーの要求は 「ユースケース¹の実行方法をすばやく理解できる」 ことでしょう
この仮定が正しければ、

結論
「わかりづらい」=「ユースケース¹の実行方法を理解するのに時間がかかる」こと ²
ちょっと長いので、以下では単に 「理解に時間がかかる」 と記述します

となります。何となくしっくりくるのではないでしょうか

どうやったら「わかりやすい」マニュアルになるのか

「わかりづらい」(=「理解に時間がかかる」)原因

まず、「理解に時間がかかる」真因をなぜなぜ分析しましょう³ ⁴
問題が具体的であるほどやりやすいので、あなたの知ってるクソマニュアルを想定して読んでください⁵

よくある真因には〇、あまりなさそうな真因には×を付けます
(結論だけ知りたい人は↓の画像を見なくても問題ありません)

結論
真因は以下の通り

目次からどのユースケースの記述があるのかわからない
ユースケースの記述が複数のページに分散している
必要以上に詳細な設計情報が紛れ込んでいる
ユースケースを実行する手順が本質的に複雑である
文の表現が冗長である
ユーザの母国語で書かれていない

真因に対する対策

目次からどのユースケースの記述があるのかわからない

問題の具体例
Yocto Project Documentation を参考に見てみましょう
(YoctoはカスタマイズしたLinuxOSのRuntimeをビルドするためのプロジェクトです)

左端に目次がありますが、ビルドのキャッシュをクリアする 方法はどこに書いてあるでしょうか？
分からないですよね。これが 目次からどのユースケースの記述があるのかわからない ということです

対策
シンプルにドキュメントの構造を ユースケース単位 にすることになるでしょう
つまり、目次が以下のようになればいいわけです

ユースケース_1
ユースケース_2
ユースケース_3
ユースケース_4
...

これならば、例えばユースケース_1を実行するときに見るべきページは明らかです

ドキュメントの構造を ユースケース単位 にすること

ただし、以下の点に注意してください

対象がYoctoのように複雑な場合、愚直にすべてのユースケースを記載するとドキュメントが爆発します
どの程度記述をサボるのかはケースバイケースですね...
対象がYoctoのように複雑な場合、使うだけでもある程度対象の構造への理解⁶が必要です
これをどのような構造でまとめるべきかは、ドキュメント構成の設計要素になるでしょう
仕様書や設計書はソフトウェアの構造を目次にすべきです
マニュアルとは目次の単位が異なるため、分離して管理したほうがよいでしょう

ユースケースの記述が複数のページに分散している

上の対策でこの真因も対策できます

必要以上に詳細な設計情報が紛れ込んでいる

問題の具体例
これは心当たりある人多いでしょう。ユースケースの説明に必要ない説明を書いてしまう問題です
よくある例として、あるユースケースで使用するツールの設計を語り始めたりするやつです

😡それは仕様書に書いて😡

対策
削除したら取り上げているユースケースを実行できなくなる記述 以外はすべて削除 or 移動しましょう
Appendixなど雑多な情報を記述する場所か、あるいは仕様書に移動するといいかも

削除したら取り上げているユースケースを実行できなくなる記述 以外はすべて削除 or 移動する

ユースケースを実行する手順が本質的に複雑である

対策
これはソフトウェアの問題です
ソフトウェアを改修するか、helperスクリプトを用意するしかないでしょう

ソフトウェアを改修する。あるいはhelperスクリプトを用意する

文の表現が冗長である

対策
推敲するしかないと思う

参考になるかもしれん資料を読んで推敲する

ユーザの母国語で書かれていない

対策
書き手の母国語で書いてしまいがちですが、ユーザの母国語に合わせるのがベスト
しかし、例えばドイツ語で書けと言われても難しいため、英語で書くしかないのでは

日本人以外のユーザがいるのであれば、英語で書く

どうしても英語が苦手なら自動翻訳ツールを使いましょう
ただし、生成物の著作権の確認はしたほうがいいです

おわりに

そのほか言っておきたいこと

ドキュメントの構造を真剣に考える人は少ない(と思う)
でもどんだけ凄いソフトウェアでも使うの面倒臭かったらみんな使わないから、マニュアルは大事
ソフトウェアエンジニアは「再利用性」を大事にする
でもマニュアルでいろんな記述を「再利用」するためにページを分けていくと、多分ソフトウェアの構造と一致します
ユースケースの構造と異なるので、わかりづらいマニュアルになる...
最後のほうまた手抜きになった。ごめんね

マニュアルを読むことで実行方法を知りたいとユーザーが思っていること ↩ ↩² ↩³
ちょっとウソ
「ユースケース¹の実行方法をすばやく理解できる」を満たさない場合は、「どれだけ時間をかけても理解できない」も含みます
でもこの場合は「わかりづらい」ではなく「わからない」と言われると思うので対象外にしました ↩
- 対策の裏返し(「~していない」など)しか原因を思いつかなくなったらそこで切り上げる
  (対策の裏返しは図には書かない)
- 5回掘り下げろとかいうのは無視する
- 「結果と原因」ではなく「全体と部分」で問題を分割したくなることがある。そこは後からわかるようにしておく
↩
ホントはやりたくない。頭の中で「これが原因だ」と思っている原因に対して後付けの理屈を捏ねる作業になりがちだから ↩
そのマニュアルを書いた人に悪いので具体例は出さないです ↩
一部の人が メンタルモデル と呼んでいるもののことです
ソフトウェアを理解した人が頭の中に持っているソフトウェアの構造のことを言いたいのですが、良い伝え方がわからないです
ソフトウェアを使用するのに必要十分な抽象度のモデルというか... ↩

😡 「わかりづらい」ってどういう意味😡