👀

読みやすい文章は、読みやすいコードの特徴と似ている

2022/09/09に公開

ドキュメンテーション

idea

背景

こんにちは、ビジネス職から少しずつ開発職に最近移行しはじめたDAIです。

さてさて、読みやすい文章（報告・連絡・相談・指示など）は、読みやすいコードの特徴にとっても似ているなと思ったので、今回はそのことについて記事にしてみたいと思います。

※ほかにもありそうなのですが、ちょっと思い出せなかったので、もしほかによさそうなものがあればコメントお願いします！

読みやすい文章の特徴

僕が見ていて、読みやすいな、と感じる文章の特徴は、以下の通りです。

用語を説明する前に定義がされている
コンテクストの共有ができている
目線を往復せずとも理解しやすい
行数が少ない

1. 用語を説明する前に定義がされている

用語が未定義のまま説明される文章は、理解がとてもしづらい傾向にあります。

例えば、経営・マーケティング用語でUnit Economicsという言葉があります。マーケティング初心者の方に、以下のような説明をしたら、多分チンプンカンプンなはずです

NG例
UEを上げるためには、LTVを上げるかCACを下げるかが必要です。

気持ちとしては、

なんだよUEって
UEの説明するために意味わからんLTVやCACって言葉が出てきて何がなんだか。

プログラミング言語だと、未定義の言葉を呼び出すと、読みやすい、とかのレベルではなく、NullPointerExceptionを出してしまいますね。

# ※ソースコードやエラー文は適当
puts "#{UE}を上げるためには、#{LTV}を上げるか#{CAC}を下げるかが必要です。"
# ==> Undefined variable "UE"

ビジネス文章でも一緒で、定義されていない言葉で説明されると、読み手としては「？」が思いつくでしょう。（ぬるぽ状態）また後続する文章も理解できないはずです。

NG例
UEを上げるためには、LTVを上げるかCACを下げるかが必要です。

この地点で、3用語がすべて知らない言葉なので、読む気がなくなりますね。
（こういう説明は、大学時代とっても多かった記憶です笑）

この場合、ぬるぽ解消のために、まずUnit Economics, Life Time Value, Customer Acquisition Costの定義が必要になります。定義があってから次に説明があると分かりやすいです。

# OK例
Unit Economics(UE)とは、xxxxxxです。
UEは、3以上であればよいとされています。
UEは、Life Time ValueとCustomer Acquisition Costから説明されます。
Life Time Valueとはxxxxxです。
Customer Acquisition Costとは、xxxxxです。
UEを上げるためには、LTVを上げるかCACを下げるかが必要です。

2. コンテクストの共有ができている

分かりやすい説明ができる人は、読み手のコンテクスト（文脈）を理解し、読み手が伝わるコンテクストで説明をしています。

プログラミングで言えば、例えば複雑な数値計算を行いたい場合、別モジュールをインポートしたりしますよね。

またすでに言語そのもので使える言語のメソッドであれば、あえてインポートする必要はありません。

このように、コンピューターがソースコードを理解可能な状態にするために、エンジニアはいろんな方法を駆使して、コンテクストが共有しながらコードを書いていきます。

ビジネス文章も同様に、人が理解できるようにするためには、相手が自分と同じコンテクスト（文脈）を共有できているか確認することが必要になります。

例えば社内向けのテキストの場合、社内共通用語モジュールがお互いインポートされているので、社内の人に伝えるべき概念や処理は、ゼロから構築しなくても事前にコンテクストを共有できますよね。

require 'Recruit'

Recruit.ATI #==> 圧倒的当事者意識
Recruit.ZD #==> ゼンゼンダメ

puts "Aさん#{Recruit.ATI}足りない。#{Recruit.ZD}"  #==> "Aさん圧倒的当事者意識足りない。ゼンゼンダメ"

上の文章は、リクルートの人が社内の人と話す分には伝わると思います。

一方で、社外向けメッセージなのに、社内共通用語モジュールをインポートしたテキストを送る場合、社外の人がテキストを読み込んだ場合にぬるぽがでます(何言ってるかわからない）。その会社の共通用語のコンテクストが共有されていないので、伝わらないのです。（こんなメッセージをすることはないと思いますが）

require 'recruit'

Recruit.ATI #==> module `Recruit` not found
Recruit.ZD #==> module `Recruit` not found

puts "Aさん#{Recruit.ATI}足りない。#{Recruit.ZD}"  #==> module `Recruit` not found

人間をコンピューターと考えたときに、コンテクストとして利用できるモジュールにはさまざまなものがあります。

社内/社外共通用語モジュール
職種/業界共通用語モジュール
習熟度別共通用語モジュール
世代別共通用語モジュール
敬語モジュール
役職モジュール

そして読み手がどのようなモジュールを持っていて、どの文章ならきっちりと解釈できるかを、書き手はぬるぽが出ないように想定しておく必要があります。

例）

社外コンサル先 -> 職種/業界モジュール
稟議 -> 役職モジュール, 職種/業界共通用語モジュール, 敬語モジュール

※余談ですが、テキストコミュニケーションが上手な人は、以下3つ能力が高いことが多いです。

利用可能なモジュールの数が多い
相手のモジュール把握能力が高い
その場で使えるモジュール把握能力が高い

3. 目線を往復せずとも理解しやすい

読みやすいテキストは、目線の移動が少なく、上から読み進めていけば、理解しやすいです。

例えば、出社するまでの処理をソースコードにするとこうなります。

# アラサー男子の出社クラス
class Syussah
   def execute 
      hamigaki()
      haiben()
      chosyoku()
      okurimukae()
      tsukin()
      dakoku()
   end
   
   def hamigaki()
      ...
   end

   def haiben()
      ...
   end
   def chosyoku()
      ...
   end
   def okurimukae()
      ...
   end
   def tsukin()
      ...
   end
   
   def dakoku()
      ...
   end
end

Syussya.execute

普通に上から読み進めていけば、

executeで関数の処理が全部実行されるんだな
execute内の処理が後から定義されているんだな
それぞれの関数を読んでみよう

と理解することができます。

一方で、以下のようなコードの場合、非常に分かりづらいです。

# アラサー男子の出社クラス
class Syussah

   def hamigaki()
      ...
   end

   def haiben()
      ...
   end
   def chosyoku()
      ...
   end
   def execute 
      hamigaki()
      haiben()
      chosyoku()
      okurimukae()
      tsukin()
      dakoku()
   end
   def okurimukae()
      ...
   end
   def tsukin()
      ...
   end
   
   def dakoku()
      ...
   end
end

Syussya.execute

この場合、上から読み進めていくと、以下のように思うはずです。

出社(Syussya)するクラスで、うんうん、歯磨きして、排便するんだな。
ん？途中で実行(execute)？なんか抽象度違くない？これは何をするんだろう？？
その次は送り迎え(okurimukae)、通勤(tsukin)、打刻(dakoku)か、、、
よし、一通り読み終わった。うん、でもやっぱり実行(execute)ってなんだろう？いったん全部のコードの関係見てみよう（もう一度一番上の関数へ目線を移動）
ああ、なるほど、実行にはすべてのクラスメソッドが実行できるようになっているんだな

最初の例の場合、上からコードを読み進めれば一発で理解できるコードだったのに、順番を変えただけで分かりづらくなりました。

これは実は①で解説した、「説明する前に定義する」にも重なるのですが、理解できない情報については何度もコードを理解するために目線を下に進んだり上に戻したりしながら、意味を確認しないといけません。そのため、同じことを書いていても認知コストが上がるのです。

理解しやすい流れで説明するためには、コツがあります。

それは、最初に結論、もしくは意図を明確に定義することです

上記の分かりやすいほうのソースコードでも、結局最初にSyussha.execute() するクラスなんだな、というのがパット見てわかるので、それ以降のソースコードが理解しやすくなります。これはこのクラスでメインで呼ばれるメソッドが一番上に書いてあるからですね。

同様にビジネス文章でも、最初に結論を書いてくれると、後から読む肉付けが非常に理解しやすくなります。

例）分かりづらい文章

明日は課長が来ないから昨日用意が必要だったテキストは今日までに準備しなくよいので、資料のプリントアウトはしなくてよいと思ったのですが、それを上司の吉田さんに話したら、「いや念のため用意しとけって。」と言われました。なので念のため資料はプリントアウトしておきますね。

例）分かりやすい文章

念のため資料はプリントアウトしておきますね。
明日は課長が来ないから昨日用意が必要だったテキストは今日までに準備しなくよいので、資料のプリントアウトはしなくてよいと思ったのですが、それを上司の吉田さんに話したら、「いや念のため用意しとけって。」と言われました。

④行数が少ない

分かりやすいビジネス文章では、必要なことが簡潔に書かれています。
これは完全にソースコードとも同様です。

書き手は長く書けば長く書くほど理解しやすいと思い長く書きますが、実際読み手は長ければ長いほど分かりづらくなります。

端的であることが分かりやすいので、削って済む文章なのであれば極力減らすと分かりやすくなります。

上記の分かりづらい文章も、本当に必要なのはこれだけだったりします。

念のため資料はプリントアウトしておきますね。

無理に肉付けしないほうが分かりやすかったりするので、結論のみ共有できると非常に分かりやすいです。

背景