マニュアルを目次から作るということの意味がわからくてリジェクトされた話

もう20年くらい前だったか、大規模プロジェクトにアサイメントされた。担当は、プロジェクト内で使用するエンジニアが使用する情報共有システムだった。サーバのセットアップ（聞いてなかった）から、パッケージの導入をさせられて（製品担当のエンジニアのオンサイトサポートがあったかもしれない）、あとはプロジェクトに合わせてカスタマイズするというやつだ。

当時のカウンタのリーダが部長級の人で、プロジェクトの中で使わせるのでマニュアルを作れという。じゃあと、作ってみたら速攻でリジェクトされた。もう一度トライしたらこれも速攻でリジェクト。

そのとき、優しく言われたのが

「目次からね。作って」

ああそうなんですね、くらいしか思いもしなかった。言われたことの意味が理解できていなかったのだ。

だからだろう、３回目もリジェクト。

わかってないので解決策が突破できずに悩むこと一日。今から思えば悠長なことだ。今だったら、すぐに相談してよ、と言うだろう。

構成を考える機会

 エンジニアであれば、文書を作成する機会は多いはずだ。仕様を説明する資料、設計書など書くことが仕事だからだ。

ただ、文書を作ると言っても、テンプレートを使って書くことが多い。テンプレート自体や、そのテンプレートを部品とした、文書全体の目次構成を考え、チームに展開する機会はほとんどないだろう。特に最近は、ドキュメント自体をUMLなどのツールで書いてしまったり、コードからリバースするところもあるから、ツールのデータをリポジトリに格納したらおしまい、的なプロジェクトもある。

ただ、そうしたツールで○○図やチャートを作成していても、プロジェクトで作成するドキュメントはコードを書く上で必要なものの構成は考えなければならない。それを考慮した上で、どの図表や文書が必要かを決めなければ、コードを書く際に情報が足らず、手戻りが発生してしまう。

結局、誰かが文書の構成を考える必要が出てくるが、誰かが考えれば良いのでその他大勢のエンジニアにそうした文書構成を考える機会は訪れない。

何が困るか

文書の構成を考える機会が得られないと何が起きるか。エンジニアが自分で一から作る文書の内容が破茶滅茶になるのだ。

wordでもpowerpointでも良いが、文書を作らせるとエンジニアが書きたいこと、書けることから書き始めてしまう。

普段から目次構成を考えることがなく、パーツばかりを作っているから文書の目次を考えると言う発想に辿り着かない。

何が起きるかと言えば、上述のようなことが起きるのだ。

何を伝えたいか

 文書であるから、結局、対象読者に対して文書に記載することを伝えたい、となるはずだ。ウォーターフォール型のシステム開発であれば、局面の文書は、次工程のインプットになる。V字モデルであれば対向するテストフェーズのインプットになる。将来の自分かもしれないエンジニアに対してその工程での成果を伝えるために作成するのだ。

成果発表であれば、伝えたい成果を最大限伝えなければ成果を評価してもらえない。過大にではなく事実としての成果を伝えなければならない。

そうした伝えたいことを伝えられる文書になるかどうかは、目次構成に全てが掛かっている。

構成を考えるには

付箋紙かA４の紙に標題、こんなことを書くと言うイメージのコメントを書き出し、壁に貼ったり、テーブルに並べて全体を眺める。

これが一番である。

その際に、伝えたいことは何か、を書き出しておくと良いだろう。順番に悩んだり、構成に入れるか、削除するかの基準となるからだ。

間違ってもいきなりWordやPowerpointで作り始めてはいけない。綺麗に仕上がるので構成を作ることより、実際に書き始めてしまうからだ。

ここは注意されたい。

SHIROBAKO Blu-ray プレミアムBOX vol.1(初回仕様版)