ソフトウェアのドキュメントには落書きを入れた方が分かりやすくなるかも

2019-12-13雑記

• 「どれだけ丁寧に説明しても、相手に仕様が理解してもらえない。どうしてだろうか？」
• 「分かりやすいドキュメントの書き方があれば知りたいな」

どうも、ベタオシです。

ソフトウェアの仕様書を提出してもなかなか理解してもらえず、打ち合わせという名の説明会を開かなければいけないことってありませんか？

組み込みソフト開発を10年以上やってきた経験から、僕がやっている相手に伝わりやすいドキュメントを作る方針やちょっとしたテクニックを紹介したいと思います。

この記事には次のことを書きました。

• 　相手に伝わりやすいソフトウェアドキュメントを作る考え方やテクニックについて

相手に理解してもらうために図やイラストを使う

ソフトウェアの説明を文章だけで行うのは難しいです。簡単な図やイラストがあった方が間違いなく理解しやすい、僕はそう思っています。

なぜなら、現実に存在するものを使った例を挙げるのが難しいことが多いためです。参考になるものが無く、実際の形が見えないソフトウェアを、文章だけで相手に伝えるのは大変ではないでしょうか。

最近では、経験の浅い若手のエンジニアに、クラスの継承を言葉だけで説明することに苦労しました。親クラスと子クラスや多重の継承について、口頭で伝えても、理解が深まらなかったんですね。

ノートに落書きしながら説明すると、徐々に分かってもらえました。イラストのお陰かなと思ってます。

この様な経験から、ソフトウェアに関するやりとりをする時は、文章だけでは相手に伝わりにくいので、普段から簡単な図やイラストを作るようにしておく方がいいと考えています。

文章よりも先に図やイラストで説明する習慣が身についていると、自分の考えていることが相手に伝わりやすくなることはもちろん、突然の説明要求にもスムーズに応えられることも利点です。

図やイラストを手軽に用意できる方法

文章より図やイラストをが伝わりやすいということは理解してもらえたとして、図やイラストを用意するのはちょっとした手間がかかるので、なかなか手が出せないですよね？僕はこの問題が多少緩和できる仕組みを作っています。

それはとても単純で、自分で作った図やイラストをため込む画集を作っておくだけです。図やイラストを用意する時は、そこにあるものをベースにすればいいわけです、これなら作業時間が短縮されるので、手軽さが出てきます。

もし参考になるものが無かったら、新しく画集に追加していきます。初回は大変かもしれませんが、次回以降は再利用することができます。

画集をどうやって作るのか？ですが、僕はどんなソフトを使っても構わないと思っています。サラリーマンエンジニアの方なら、エクセルやパワーポイントがいいのではないでしょうか。会社支給のPCならインストールされている可能性は高いと思われるので。

個人的には、手書きメモを取り込めるようになっている環境が一番いいと感じます。さっと落書きして、それを資料に張り付けてしまうのです。

残念ながら、僕の環境は会社支給PCと私物のスマホやPCを接続することやデータのやり取りをすることは禁止なので、実際に行うことはできません。

良さそうと思ってはいるのですが、実際に試していないので、この方法には何らかの落とし穴があるかもしれません。

UMLという統一モデリング言語を使えば、ソフトウェアの設計を一定のフォーマットに従って視覚的に表現できます。自分画集がある程度の規模になってきたら、レベルアップとしてこちらを学ぶのもいいと思います。

ただし、エクセルやパワーポイントはUMLを表現することには向いていないので、もう少し高度なソフトが必要になってしまいます。

他人に資料を回覧することを考えると、汎用的な形式のファイルであることが望ましいので、導入は難しいかもしれません。もちろん、UMLを記述できるソフトにはPDF等のフォーマットでファイル出力できる機能があるとは思いますが。

まとめ

伝わりやすいソフトウェアドキュメントを作る考え方やテクニックについて、紹介しました。

図やイラストを使えば分かりやすいということは理解出来ているんだけど、準備が面倒なんだよねと言う方は、自分画集をチームで作ってしまうのがいいですよ。別に一人でやり遂げなければいけないものでもありませんから。

それではまた、ベタオシでした。