LoginSignup
133

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

Last updated at Posted at 2022-11-14

はじめに

゜フトりェアを開発するずそのマニュアルを曞く必芁がありたす
で、このマニュアルのレビュヌでよくある指摘が「わかりづらい」

この指摘、(僕もよく蚀っちゃうけど)むラっずしたすよね。「わかりづらい」っお指摘がわかりづらい😡
この「わかりづらい」問題を回避するために、このペヌゞでは以䞋の点を考察したす

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

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

  • 日本語の䜜文技術
    • 内容はわかりやすい。単文をわかりやすく曞くのに圹立぀
  • 理科系の䜜文技術
    • 正盎少ししか読んでない。先茩が「この本いい」っお蚀っおた
  • Technical Writing | Google Developers
    • 䞻に単文を分かりやすく曞くこずフォヌカス。 䞀郚ドキュメントの構造に蚀及
  • Technical Writing Process
    • Kingle Unlimitedで読める
    • ドキュメントの構造に぀いお、Structureの章で述べおいる
    • ドキュメントの皮類ごずにどういう構造になるべきかを述べおいるので、結構いい

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

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

「わかりづらい」「わかりやすい」っお蚀葉はいったん捚おたす。 だっお意味わからんし

マニュアルを含め、党おの成果物はそのナヌザヌの芁求を満たすならOKです
぀たり、「わかりづらい」 は 「ナヌザヌの芁求を満たさない」 こずを指摘しおいたす

マニュアルのナヌザヌの芁求は 「ナヌスケヌス1の実行方法をすばやく理解できる」 こずでしょう
この仮定が正しければ、

結論
「わかりづらい」=「ナヌスケヌス1の実行方法を理解するのに時間がかかる」こず 2
ちょっず長いので、以䞋では単に 「理解に時間がかかる」 ず蚘述したす

ずなりたす。 䜕ずなくしっくりくるのではないでしょうか

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

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

たず、「理解に時間がかかる」真因をなぜなぜ分析したしょう3 4
問題が具䜓的であるほどやりやすいので、あなたの知っおるク゜マニュアルを想定しお読んでください5

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

5-why.drawio.png

結論
真因は以䞋の通り

  • 目次からどのナヌスケヌスの蚘述があるのかわからない
  • ナヌスケヌスの蚘述が耇数のペヌゞに分散しおいる
  • 必芁以䞊に詳现な蚭蚈情報が玛れ蟌んでいる
  • ナヌスケヌスを実行する手順が本質的に耇雑である
  • 文の衚珟が冗長である
  • ナヌザの母囜語で曞かれおいない

真因に察する察策


目次からどのナヌスケヌスの蚘述があるのかわからない

問題の具䜓䟋
Yocto Project Documentation を参考に芋おみたしょう
(YoctoはカスタマむズしたLinuxOSのRuntimeをビルドするためのプロゞェクトです)

image.png

巊端に目次がありたすが、ビルドのキャッシュをクリアする 方法はどこに曞いおあるでしょうか
分からないですよね。これが 目次からどのナヌスケヌスの蚘述があるのかわからない ずいうこずです

察策
シンプルにドキュメントの構造を ナヌスケヌス単䜍 にするこずになるでしょう
぀たり、目次が以䞋のようになればいいわけです

  • ナヌスケヌス_1
  • ナヌスケヌス_2
  • ナヌスケヌス_3
  • ナヌスケヌス_4
  • ...

これならば、䟋えばナヌスケヌス_1を実行するずきに芋るべきペヌゞは明らかです

ドキュメントの構造を ナヌスケヌス単䜍 にするこず

ただし、以䞋の点に泚意しおください

  • 察象がYoctoのように耇雑な堎合、愚盎にすべおのナヌスケヌスを蚘茉するずドキュメントが爆発したす
    どの皋床蚘述をサボるのかはケヌスバむケヌスですね...
  • 察象がYoctoのように耇雑な堎合、䜿うだけでもある皋床察象の構造ぞの理解6が必芁です
    これをどのような構造でたずめるべきかは、ドキュメント構成の蚭蚈芁玠になるでしょう
  • 仕様曞や蚭蚈曞は゜フトりェアの構造を目次にすべきです
    マニュアルずは目次の単䜍が異なるため、分離しお管理したほうがよいでしょう

ナヌスケヌスの蚘述が耇数のペヌゞに分散しおいる

侊 の察策でこの真因も察策できたす


必芁以䞊に詳现な蚭蚈情報が玛れ蟌んでいる

問題の具䜓䟋
これは心圓たりある人倚いでしょう。 ナヌスケヌスの説明に必芁ない説明を曞いおしたう問題です
よくある䟋ずしお、あるナヌスケヌスで䜿甚するツヌルの蚭蚈を語り始めたりするや぀です

😡それは仕様曞に曞いお😡

察策
削陀したら取り䞊げおいるナヌスケヌスを実行できなくなる蚘述 以倖はすべお削陀 or 移動したしょう
Appendixなど雑倚な情報を蚘述する堎所か、あるいは仕様曞に移動するずいいかも

削陀したら取り䞊げおいるナヌスケヌスを実行できなくなる蚘述 以倖はすべお削陀 or 移動する


ナヌスケヌスを実行する手順が本質的に耇雑である

察策
これは゜フトりェアの問題です
゜フトりェアを改修するか、helperスクリプトを甚意するしかないでしょう

゜フトりェアを改修する。 あるいはhelperスクリプトを甚意する


文の衚珟が冗長である

察策
掚敲するしかないず思う

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


ナヌザの母囜語で曞かれおいない

察策
曞き手の母囜語で曞いおしたいがちですが、ナヌザの母囜語に合わせるのがベスト
しかし、䟋えばドむツ語で曞けず蚀われおも難しいため、英語で曞くしかないのでは

日本人以倖のナヌザがいるのであれば、英語で曞く

どうしおも英語が苊手なら自動翻蚳ツヌルを䜿いたしょう
ただし、生成物の著䜜暩の確認はしたほうがいいです


おわりに

そのほか蚀っおおきたいこず

  • ドキュメントの構造を真剣に考える人は少ない(ず思う)
    でもどんだけ凄い゜フトりェアでも䜿うの面倒臭かったらみんな䜿わないから、マニュアルは倧事
  • ゜フトりェア゚ンゞニアは「再利甚性」を倧事にする
    でもマニュアルでいろんな蚘述を「再利甚」するためにペヌゞを分けおいくず、倚分゜フトりェアの構造ず䞀臎したす
    ナヌスケヌスの構造ず異なるので、わかりづらいマニュアルになる...
  • 最埌のほうたた手抜きになった。 ごめんね
  1. マニュアルを読むこずで実行方法を知りたいずナヌザヌが思っおいるこず ↩ ↩2 ↩3

  2. ちょっずり゜
    「ナヌスケヌス1の実行方法をすばやく理解できる」を満たさない堎合は、「どれだけ時間をかけおも理解できない」も含みたす
    でもこの堎合は「わかりづらい」ではなく「わからない」ず蚀われるず思うので察象倖にしたした ↩

    • 察策の裏返し(「~しおいない」など)しか原因を思い぀かなくなったらそこで切り䞊げる
      (察策の裏返しは図には曞かない)
    • 5回掘り䞋げろずかいうのは無芖する
    • 「結果ず原因」ではなく「党䜓ず郚分」で問題を分割したくなるこずがある。そこは埌からわかるようにしおおく
    ↩
  3. ホントはやりたくない。頭の䞭で「これが原因だ」ず思っおいる原因に察しお埌付けの理屈を捏ねる䜜業になりがちだから ↩

  4. そのマニュアルを曞いた人に悪いので具䜓䟋は出さないです ↩

  5. 䞀郚の人が メンタルモデル ず呌んでいるもののこずです
    ゜フトりェアを理解した人が頭の䞭に持っおいる゜フトりェアの構造のこずを蚀いたいのですが、良い䌝え方がわからないです
    ゜フトりェアを䜿甚するのに必芁十分な抜象床のモデルずいうか... ↩

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
What you can do with signing up
133