文書の指導（２）

前回の記事「文書の指導」では、文書をチェックして修正させるためには、「部下と上司の関係の上で成り立つ行為」と述べていますが、社外へ公開する文書についても、チェックして修正させる部門や部署があるわけです。何もチェックされることなく、社外へ公表されることはないかと思います。

一方、昔と違って今日では、技術系のTech Blogを書くことを社員に推奨して、自社のサイトで公開する企業が多くなっています。そのような技術ブログの場合、どのようなチェック体制なのかは、企業によって異なっているのではないかと思います。たとえば、Tech Blogを公開する前に必ずビューを行う担当者や組織があったり、マネージャによるチェックおよび承認が必要であったり、本人任せになっていたりとさまざまだと思います。開発組織がフラットであれば、Slackの専用のチャネルを通して、誰ともなくレビュー依頼を出してレビューしてもらうのかもしれません。

私自身、一人のソフトウェアエンジニアとして、勤務時間はほぼプログラミングを行っています。富士ゼロックスグループやリコーで行っていたような、作成された文書をチェックして修正を指導する部下は持っていません。私自身は楽ですが、その一方で思うのは、まわりの若手のソフトウェアエンジニアの人達は、指導を受けて、文書を書くスキルを伸ばす機会が得られないまま年を重ねていくのではないかということです。同じことが、「API仕様を書く」で述べた事柄に関しても当てはまります。

文書の指導

ソフトウェアを開発する際には、プログラミングしてコードを書くことに加えて、さまざまな文書を書きます。文書を書く上で、読み手が理解できるか否かを考えることは重要なのですが、自分では理解できるだろうと思っても、実際には理解しにくことがあります。また、作成する文書によっては、書き方のフレームワークがあることがあります。

フレームワークとして企業内における昇格時の昇格レポート（昇格論文）を例として挙げます。昇格レポートのフレームワークに関しては企業の特色が出てきます。たとえば、私が一番長く勤務した富士ゼロックス（および富士ゼロックス情報システム）では、QCストーリ的な組み立てが求められていました。それは、以下のような骨格です。

• 担当業務の説明
• 課題（問題）は何か
• 課題の原因を分析
• 改善策の検討
• 改善策の実施結果と効果
• 残された課題に対する今後の方針

大枠はこのような感じで、課題は2つは書く必要がありました。そして、これらをA4の2ページに論理的にまとめる必要がありました。すべての昇格でこのようなレポートを書くことが求められていました。昇格の種類によっては面接も行われますし、レポートだけで判断される場合もあります。

当然、昇格ごとに、レポートを作成して、上司にチェックしてもらい、提出締切のギリギリまで修正を行うことになります。一方、上司の立場からすると、最初は部下に任せて書かせて、その後、さまざま指摘をしながら、何度も修正させます。

当時、このような昇格レポートの作成やチェック、それに審査は面倒だなと思っていました。しかし、振り返ってみると本人にとってはかなりよい文書作成のトレーニングになっていたと思います。そのことを痛感したのは、リコーに勤務していたときです。

リコーでは富士ゼロックスと異なり、昇格ごとにレポートを書く必要がなく、管理職になるまでに2回しかレポートを書かない人事制度になっていました。私自身は昇格の審査をしたことはありませんでしたが、事業部内で昇格の面接練習の面接官として、何度か昇格レポートを読んだことがあります。しかし、そのほとんどがQCストーリ的な論理建てがほとんどなく、私にとっては分かりにくいレポートが多かったです。

技術者であれば技術レポートを書くことも多いと思います。技術レポートも上司からチェックしてもらい、第三者が読んでも理解できるものにしていくことが重要です。チェックして修正させるのは、昇格レポートと同様に、「部下と上司の関係の上で成り立つ行為」ではないかと思います。私自身も、開発の部門長や開発グールプのリーダーをしているときは、技術レポートもかなり手直しさせていました。

私自身がいつもきちんとしたものを書けるわけではありませんが、文章を書く訓練ができていない若手のエンジニアが指導される機会もなく、年齢を重ねると、指導する側になることもなく成長しないのではないかと思います。Wikiに書く簡単なまとめから、さまざまな文書まで、第三者が読んで誤解なく理解できるかに関して指導を受けていく必要があると思います。そして、自分自身で一歩下がって、自分が書いた文章を第三者が理解できるかを意識して見直していく必要があります。

不具合が発生した場合、必ず再現テストを書く

ソフトウェアを書いて、手作業でテストする手法とは異なり、テスト駆動開発ではいくつかの規律が求められます。その中で、「テスト駆動開発の経験（6）」で述べたことの一つが「不具合が発生した場合、必ず再現テストを書く」です。

不具合への対処は次のようなステップとなります。

1. 不具合が発生した際に、その原因を調査します（「デバッグの科学的手法」）
2. その不具合を再現させるテストを作成します（不具合が存在するために失敗するテストです）。
3. テストが失敗するのを確認します。
4. 不具合の原因を取り除いて修正します。
5. テストが成功するのを確認します。

マルチスレッドプログラミングでは、原因の調査および再現テストを書くことが非常に困難な場合があります（「マルチスレッドプログラミングにおける重要な４要件」）。その場合の再現テストは、普通の再現テストとは異なる工夫が必要になります（詳細については別の機会に書きたいと思います）。

テスト駆動開発をしていても、原因が分かった時点で再現テストを書くことなくコードを修正する衝動にかられて、コードを修正してしまう開発者も多いのではないでしょうか。実際、再現テストのコードの量よりも、不具合の修正コードの量の方が圧倒的に少ない場合があります。

資産としてのテストを蓄積していくことはテスト駆動開発では重要であり、すべての蓄積されたテストを実行することで、テストがカバーしている範囲の機能が正しく動作しているという安心感が得られます。もちろん、テストに抜け漏れがあるから不具合が見つかるわけですから、新たに見つかった不具合に対して再現テストを書いてさらにテスト資産を蓄積するわけです。その場合、見つかった不具合の再現テストに加えて、類似の原因の不具合があることが分かれば、追加の再現テストも作成して、コードを修正することになります。

再現テストの作成をスキップしがちな場合、意識して再現テストを書く努力をして、「不具合が発生した場合、必ず再現テストを書く」習慣を身につける必要があります。