仕事をしていくうちに、どんどんノウハウを積み重ねていき、どんどん仕事が楽になる。その結果、どんどん生産性があがり、どんどんボーナスも増えて行く。すごく理想的ですね！

同じソフトウェアを作るにしても、そのスピードは人によって数倍～数十倍の差があると言います。これは個人的な意見ですが、「正しいやり方を知っているか否か？」が、このスピードに対する重要なファクターの１つではないかと思います。

「正しいやり方」というノウハウを積み上げて行くには、「いかに分かりやすく書くか？」が重要です。そこで今回は、私が普段考えている、技術ノウハウの文書化方法について書いてみます。

まず、技術文書は大別して「マニュアル的」なものと、「ハウツー的」な物に分かれると考えています。

図１　マニュアル的な文章は、機能列挙型

マニュアル的な文章とは、どういう機能があるのか？をひたすら列挙している文書のことです。読むのにすごく時間がかかりますが、製品の機能を１００％網羅してくれます。

図２　ハウツー的な文章は、機能の組み合わせ方を示す

ハウツー的な文章とは、○○するにはどうしたらいのか？が書いてある文章のことです。読む時間を最小限にして、最大限の効用が得られるように書いてあります。

では、これらをどのように使い分け、どのように書いていったら良いのでしょうか・・・？

「理解」と「効用」のバランス

マニュアルとハウツーは、どのように使い分けるのでしょうか？それは、目的の違いによると思います。

製品や技術について「理解」したいのであれば、マニュアルをしっかりと読みこなす必要があります。

一方、「効用」だけ欲しいのであれば、ハウツーの書かれている通りにすれば良いです。

「効用」だけ欲しいというのは、たとえばこうです。回路設計をする際、いくつかの抵抗値などを最適に設計する必要があります。本来であれば、そのために回路網のインピーダンスを計算するなりして回路特性を解析します。その上で、求める性能が得られるように抵抗値などのパラメータをチューニングします。

しかし、最近のツールをつかうと、すごく楽にできます。回路図をお絵かきして、あとはボタンを押すだけ。すると、回路特性を自動的に計算した上で、パラメータスイープなどを行い最適値を勝手に見つけてくれます。

このように、何も知らなくてもボタンさえ押せば「効用」が得られるわけです。もちろん、計算方法をすべてマスターしたうえでこういったツールを使うのであれば良いのですが、何も知らずに「効用」だけ欲しくてこの手のツールを使うと、間違いなく堕落します。

さて、それでは読み手を堕落させないよう「理解」もしてもらいつつ、一方で「効用」を手っ取り早く得てもらうにはどうしたらいいのでしょうか？

それには、マニュアルとハウツーを行ったり来たりしてもらうのが一番かと思います。当然、そういった使い方を想定して、マニュアルなりハウツーなりを書かないといけません。

たとえば、ハウツーの各所からマニュアルに対してリンクを張り、参照しやすくする、などの工夫が必要です。

さて、これまではマニュアルとハウツーの使い分けの話でした。ですが、マニュアルとかハウツーとかに関わりなく、もっと根本的で重要なポイントがあります。それは「抽象化」です。次の章では、「抽象化」について見て行きます。

マニュアル的文章を分かりやすくするには？

マニュアル的文章の目的は、機能を「理解」してもらう事にあります。一方で、網羅率１００％を目指して、あれもこれもと書いていかなくてはいけません。

何も考えずに書き始めると、問題が起きます。それは、「読まないといけない量が多すぎて、読む気が無くなる」という現象です。これは、いろんな機能について、いきなり具体的な話を延々と列挙し始めた時に起こります。

そもそも全ての読み手が、内容を１００％理解する必要などないはずです。ですから必要な時に、必要な部分だけを「理解」してもらうための仕組みが必要です。

そこで、抽象化という作業を行います。

抽象化とは？

正確には、「抽象化」と「具体化」がポイントです。

抽象化とは、「要するに？簡単に言うと？」という質問に答える事です。

具体化とは、「具体的には？詳しく言うと？」という質問に答える事です。

たとえば、RTAI入門の記事から「リアルタイムタスク」についての説明を拾ってみます。

抽象化された文章とは、この記事にあるように、

RTAIの機能で、Linuxのユーザープロセスをリアルタイム化できます

と、簡略に述べらています。これを「具体的には？詳しく言うと？」と問うと、以下のようになります。

すなわち、具体化された文章では、この記事にあるように、

・リアルタイム化するには・・・うんうんかんぬん
・リアルタイム化する意味とは・・・うんぬんかんぬん

と、すごく詳細に述べられています。これを「要するに？簡単に言うと？」と問うと、上記のようになります。

これは、「リアルタイムタスクとは？」を、抽象化したり具体化したりしている例です。

では、この「抽象化」という作業を、マニュアルに対してどのように行えば良いのでしょうか・・・？

マニュアルにおける抽象化ツリー

話の全体がみえないと、すっごくイライラしますよね？だから、まずはマニュアル全体をすごくすごく抽象化して、簡単に見せてしまいます。

RTAI入門の場合、この記事がそれにあたります。RTAIって一体全体何ができるの？が一目でなんとなく分かります。この記事を見ると、とりあえず全体を把握している感というものがあって安心できます。これは、後に続く記事の内容をものすごく抽象化してまとめたものです。

あとは、リアルタイムタスクなり、メッセージなりの個別の要素を少し具体化しています。来週以降の記事では、いよいよ具体的なCコードが出てきます。これは、ものすごく具体化されているレベルで、実際に機能を使うには、このレベルまで降りてこないといけません。

図３　階層構造を１段ずつ降りて行きながら、必要な部分の知識だけを選択して得て行く

さて、実際にマニュアルを書く段になったとしましょう。まず始めは、あまり抽象度の事は気にしなくてもOKです。どんな抽象度でも構わないので、頭に浮かんだ物から書き始めて下さい。どこから書いても構わないので、とにかく書きながら、次の作業を行いましょう。

• 全体が一目で見渡せるまで、抽象化する（要するに？）
• 操作方法、参考コードなど、具体的手順が見えるまで具体化する（具体的には？）

このように、文章を書いたあとで、さらにそれを抽象化したり具体化したりした文章を書く。このようにして、抽象化ツリーを作り上げて行きます。

どこから書き始めても、「要するに？簡単に言うと？」や、「具体的には？詳しく言うと？」という質問に答えながら文章を描き足していくだけで、自然とツリーが出来上がります。

この作業の事を「構造化」と呼び、ソフトウェア設計などではおなじみの手法です。出来上がったツリーは、そのまま目次の構成とする事が可能です。

抽象化ツリーの利点

マニュアルをきちんと構造化して、抽象化ツリーを作ってあげるとこんな利点があります。

まず、読み手はトップレベルの文章を読むだけで全体が把握できた気分になるので、イライラしにくくなります。

そして、「読み手にとって必要な知識は、だいたいどのあたりにあるか？」が、ツリー構造から分かります。そのため読み手は、必要な部分だけを必要なレベルまで読み下げていく事ができます。

たとえばRTAI入門を、「１ｍｓ毎にI/Oボードを動かしたい」、という人が読んだとします。この人は、まず全体マップを見て、「関係ありそうなのは、リアルタイム化と、タイマーによるトリガーだけだな」と分かります。あとは、「リアルタイム化」と「タイマーによるトリガー」の、より詳しい概念をここで知ります。最後に、来週以降の記事から、リアルタイム化やタイマートリガーの部分のソースコードをコピペしてしまえば、作りたいアプリを作れてしまいます。

このように、抽象化ツリーによって読み手にかかるコストを最小限に抑える事が出来るようになります。

ちなみに、さまざまな技術書を日本人も欧米人も書いています。それらを読んでいて思うのは、欧米人の書いた文章のほうが、抽象化ツリーの階層が深い、という点です。

日本人が書く文章は、あまり上の方に抽象化されておらず、いきなり詳細がべったり書かれているように思います。一方、欧米人の書く文章は、最初に原理原則を示し、それから具体的な詳細に降りて行く、というパターンが多いように思います。（あくまで傾向の話なので、例外はいくらでもあります。）

そこで、あまり構造化されていない文章を読む時は、あえて自分で抽象化・具体化を行って抽象化ツリーを作る事にしています。そうすると、全体が見渡せる上に理解も深まります。しかも、抽象化のトップレベル階層をざっと読み返すだけで、簡単に復習ができるようになるため、とても便利です。

ハウツー的文章を分かりやすくするには？

ハウツーの場合は、とにかく「効用」を得るための具体的な手順を書くのが目的です。

ですから、抽象化ツリーを作るべき場合と、そうでない場合に分かれます。

抽象化ツリーを作るべきでない場合

作るべきでない場合とは、やるべき手順が簡単な場合です。

たとえば、「このコードをコピペして、ちょこっとパラメータさえ変えればいいよ！」というようなテンプレート的コードを示す場合、あえて内容を詳しく説明する必要はありません。

ハウツーの目的は、「最小限の努力で、最大限の効用を得ること」にあります。理解してほしいポイントがあるのであれば、マニュアルにリンクを張って、マニュアル側で解説するべきです。

ですから、やるべき手順が簡単な場合は、余計な説明は不要で「いいから、黙ってこの通りにしてごらん。うまくいくから」というスタンスで書くのが良いと思います。

抽象化ツリーを作るべき場合

ハウツーでは、「いいから言う通りにやってみな」という風に書きます。しかし、その手順自体が結構複雑な場合もあります。

そういう場合には、やっぱり抽象化ツリーを作って、手順全体を見渡せるようにしておくべきです。

図４　What-How変換を利用して、手順を構造化する

たとえば、RTAI環境の構築方法の記事をご覧ください。

まずは、

Linuxマシン１、Linuxマシン２に、Scicos、RTAI-Lab、
モデルのリアルタイム動作環境をそれぞれ作るよ

と示しています。

そうしたあとで、具体的なインストール方法について、

ここからあれをダウンロードして、コマンドラインにこう入力して・・・

といった風に触れています。

これをWhat-How変換と呼んでいます。すなわち、

What：「Scicos、RTAI-Lab、リアルタイム動作環境をインストールする」

How：「ここからソフトをダウンロードして、コマンドラインでこう入力して・・・」

というように、What（何を？）とHow（どうやって？）を変換していきます。

RTAI環境の構築の場合は、この階層が２つだけです。しかし、もっともっと複雑な手順が必要であれば、もっともっとWhat-How階層を増やしていきます。

こうすることで、常に全体を見渡しつつ、今何をしているのかを把握する事が出来ます。

注意していただきたいのは、ここで把握するのは「全体の手順」であって、決して「技術的な背景」ではない、という事です。

読み手に対して技術的な「理解」をさせたいのであれば、それはマニュアル側でやるべきです。もちろん、ハウツー側でちょこっと技術的内容に触れるのは構いません。しかし、本格的に説明しだすと「最小限の努力で、最大限の効用を」という原則をやぶってしまいますので、注意が必要です。

まとめ

まとめますと、

• ノウハウを文書化するにあたって、２種類の方法がある
  • マニュアル的文章は、機能を列挙する。読み手に「理解」を促すのが主目的
  • ハウツー的文章は、手順を列挙する。読み手に「効用」をもたらすのが主目的
• マニュアルにせよ、ハウツーにせよ、抽象化と具体化による構造化を行うべし

こんな感じになります。

但し、実際にはマニュアルとハウツーの境界は結構あいまいだったりします。ですから、そのあたりは読み手のレベルにあわせて適宜調整していくと良いかと思います。

次回

次回は、どうやってやるのか？編その１として、タスク制御、メッセージ制御のためのコードを見て行きます。