検証どうでしょう 【最終話】
この企画は、累々とエンジニアの屍の上に成り立ってきたIT業界に、またたび。。。。もとい、ジャーキー。。。。
いやいや一石を投じる、ハードで尖った内容である・・・・日本の未来のIT業界のために、立てよエンジニア！！
世界の「ピンフ」のために立ち上がれ！！
～寝れないんだよ ドキュメント作成しないと寝れないんだよオレたち編～
ブログを訪問いただいている皆様へ
検証どうでしょうを楽しんでいただきましてありがとうございました。
中の人、です。
本配信にて、検証どうでしょうは最終回となります。
検証どうでしょうは、北海道愛あふれる旭川出身の「中の人」が面白おかしく大切なことを伝えようと企画されました。
もともとはテストのことを題材に進めようと考えておりましたが、少し上流から、設計に関する事柄をお伝えしようと考えておりました。
中の人はコンサルタントでもあるので、お客様から様々な相談があります。
もちろんソフトウエアの品質保証からテストに関することが多いですが、上流の品質を上げたい、最近のエンジニアがうまく設計できないという相談が増えています。
設計自体がうまく行っていない、というスタートラインですが、よくよく分析すると、実は文章でうまく表現できていないことを先に解決する必要がある、という結論に至りました。
そこで、まずは簡単なところ、自分である程度チェックできるようになるといいな、というふうに路線を変更しました。
コンサルタントの書く文章は少し硬いものが多く、もっとライトに読んでいただきたく、このような企画になりました。
「毎回楽しみにしている」、「若いエンジニアに読ませている」、「写真だけ見に来ている」などなどとても嬉しい反響をいただきました。
かなりゆるく作っているので、写真のインパクトが大きくて実は頭に残らないだろうなというふうに思っており、それでもいいんじゃないかと進めてきました。
とはいえ、最後は少し格好良くまとめさせていただけたらと最終回に「中の人」が登場する、ということになりました。
まずは、奥義を覚えていただきたいなと思います。
奥義をもっと細かくお話してゆきましょう。
奥義
①記載粒度を確認せよ。
②記載漏れがないか。
③上から下へ文章が構成されているか。
④想定読者むけになっているか。
⑤日本語の「てにをは（＋ がのも）」は問題ないか。
⑥使用しているフォーマットは指定されたものか。
⑦プロジェクトで定義されているもの、社内で定義されているものなどに統一されているか。
⑧適時参照を使っているか。参照先は正しいか。
⑨複雑なビジネス、システム化の背景、ロジック等の場合、適宜図や表を使用しているか。
⑩参照情報・添付資料に不備はないか。
⑪セルフチェックしているか。ピアレビューしているか。
と書きましたが、本当はもっといっぱいあるんですよ(^_-)-☆
しかし、まずはこれくらい注意しようと思ってください。すると、レビューでつまらない指摘をうけないとかレビューのレベルが上がった（当社比）とかとか、体感できると思います。
これくらいはやってきてよ～ってなるのか、これくらいはレビューで必ずやろうなのか、立場によって使い方は違うと思いますが、使い続ければ、自然とだめな文章に違和感を持つようになります。
これ自分で不思議な感覚になります。今まで大丈夫と思ったことを直感的に、少し見直そう、という気持ちになります。
そうなるとわかりやすいって何だろうっていうのがだんだん自分なりに考えがまとまると思います。
さて、これらを簡単に説明してゆきましょう。
①記載粒度を確認せよ
書きっぷりとかどこまで書くのかとか、かっこよく言うとスコープみたいな話でしょうか。
これは文章の想定読者によって決まってくると思います。
またそもそもですがその文章の目的があるはずです。
文章の想定読者×文章の目的で決まってくるでしょう。
②記載漏れがないか。
本当に漏れているものを指しているわけではないです。AとBのことを書くはずがAしか書かないという意味ではありません。もちろんそれは確認してくださいね。
これは、書いているあなたは理解しているので、わかりますが要するに説明不足がないか、ということです。文章を読んで、うーんわからない説明してもらおう、説明を聞いたらよく分かった、これがないようにということです。
レビューの時は説明をするので、わかったような気がするんですね。これはレビューアーも気をつけないとだめな落とし穴です。
説明がなくてもわかるようにってことですね。大切なことが抜けているということがないように。
わからないと言われて説明して、それを書きましょう、と言われたことがないですか？
それのことです。
③上から下へ文章が構成されているか。
文章だから当たり前じゃないかって思いますよね。
違うんですよ。皆さんも経験がないでしょうか？レビューをしていて、？これはどういうこと？って確認すると、得な顔をして資料をスクロールする人がいますよね？
それって、上から下という組み立てができていないってことなんですよ。基本的には流れるように書かれていなければいけないということです。
簡単そうでむずかしい。でもこれができたらすごく読みやすいですから、気をつけてみてくださいね。
説明しながらスクロールしたくなったら、もう一度見直しが必要です。
④想定読者むけになっているか。
粒度のところでも書きましたが、誰向けですか？これすごく大切なんですよ。レビューアーをやるひと、少なくともあなたは読者じゃないんですよ。これが難しい。レビューを難しくている一つの要素だと思います。
レビューの場はほとんどが想定読者じゃないことが多いんですよ。当然理解できちゃう。
いやこれは経験年数3年以下の人が読むんだ、と想定読者があるのであれば、少しスピードを落として考えてみましょう。
そもそも文章は、その文章が不十分でも十分に読み解くことができる人向けではない、ということを考えるといいと思います。
また、書いた本人が担当を外れても、文章だけは生き残ると考えましょう。
⑤日本語の「てにをは（＋がのも）」は問題ないか。
これ、気が付かない人多いんですよね。トレーニングだと思って頑張ってみてください。
文章を読むと違和感を持つ、それの正体は、これであることが多いです。
書いて読む、これを繰り返すといいと思います。
概ねこうなっているか今一度確認してみてください。
・主語を表す「が」と「は」
・目的を表す「が」と「を」
・場所を表す「で」と「に」
・行き先を表す「に」「へ」「まで」
⑥使用しているフォーマットは指定されたものか。
フォーマットはノウハウの蓄積されたものです。それが最新であるということは非常に重要。
古いフォーマットで十分な設計書ができたとしてもそれは、評価ゼロですよね。
せっかく作ったのに評価がゼロ。恐ろしいですね。
気を付けましょう。
⑦プロジェクトで定義されているもの、社内で定義されているものなどに統一されているか。
私たちのような外からお客様のところで仕事をする場合、単語の定義やスコープなどを気にします。
会社の同僚でも、単語が指し示す意味が微妙にずれていることがありますので、注意しましょう。
当たり前を確認する、これにつきます。
新しい言葉、特殊な用語は、その説明を行うか、良い参照先があれば、参照するようにしましょう。
⑧適時参照を使っているか。参照先は正しいか。
コピペをたくさんしている資料があるのですが、それはできるだけやめましょう。
メンテナンスするのが大変なんですよ。
なので適時参照はつかうべきです。すぐ使いたいからとコピペしてはいけません。
⑨複雑なビジネス、システム化の背景、ロジック等の場合、適宜図や表を使用しているか。
難しく書く人がいるんですよ。スキルも高くて、頭もいい。だからこそやっちゃう。。。。。
簡単な相関図のようなものを書くだけで文章が半分になったりします。
文章で立体的な関係性を説明できますが難しい。しかし図に書くだけで相当労力が減ります。
デジタルで考えてイメージはアナログで、という感じでしょうか。
⑩参照情報・添付資料に不備はないか。
せっかく参照するためのポインター情報を載せても、それが間違っていたら、あなたがいないと完全に理解ができない文章となってしまいます。
最後の最後、確認しましょう。
⑪セルフチェックしているか。ピアレビューしているか。
①～⑩を文章が出来上がってからチェックしてみてください。随分と印象が変わりますよ。
さて皆さんどうでしょうか。ちょっとしたきっかけで分かりやすくうまく伝えることができます。
良い文章は「可読性」（文章が読み やすいか）、 「視認性」（パッと見た瞬間 の認識しやすさ）、「判読性」（誤読が ないか）のこれらに気を付けて書かれた文章と言われています。
正直言うと人に説明して同じようにしてもらうのは大変な労力が必要です。しかし、これらを注意して作る文章があればその労力を減らすことはできるのです。
本当に効率がいいのはきちんと文章を残す、ということです。
皆さん、ここまでありがとうございました。ちょうど春ですね。もしこれを読んでいる新社会人の皆さん。これを使ってスタートダッシュしてくださいね。
さて今回で検証どうでしょうは最終回となります。皆様当企画を楽しんでくださいましてありがとうございました。
また、違う企画が動き出しています。
次に皆様にお会いできることを楽しみにしております。
中の人、こと、代表取締役岡田篤彦
これまでの連載でお伝えしてきた内容をまとめたドキュメント作成セルフチェックリストを作成しました。 春に入社される新入社員の皆さまの準備や学びをサポートするための資料です。 ぜひ、貴社の新人教育にお役立てください。
