Excelアジャイル技術文書作成術

2021年10月16日

Excel文書作成問題の本質

Excelを用いた文書作成は不当に低く評価されている。その批判の多くは論理性や具体性に乏しく、批判する者のスキルや思考力の低さを露呈している[1] … Continue reading。そういったレベルの低い批判、いや言いがかりと言っていいだろう、に対する反論は以下の記事に任せる。

Excel で設計書作るのそんなに悪いことか? – Neo’s World

そうした中、数は少ないものの的確な批判もある[2]きっと優秀なエンジニアなのだろう。例えばこれである。

その論点をまとめると、「紙を前提にした文書に不適当という一言につきる。

確かに紙出力を想定した場合、次の2点は致命的である。

  • 不完全なWYSIWYG
  • 自動的な目次・連番作成機能がない

「神エクセル」などと揶揄される奇怪なフォーマットもほとんどは紙出力を模擬しよう苦戦した結果である。適性のないツールを無理して使っているのが問題の根源なのだ。

アジャイル開発における文書作成

アジャイル開発でもそれなりのドキュメントは必要

益々変化の加速する世界に適応する開発管理手法として、アジャイル開発が盛んになっている。

アジャイル開発においては、ドキュメントの作成は「必要最小限」とあり、開発環境ごとにテーラリングすることを前提だ。

よくアジャイル開発のドキュメント例に挙げられる、手書きの図とテキストファイルは、少数の優秀な開発者が膝突き合わせて開発し、プロジェクトチームに対するプロジェクトオーナーの信頼も厚い限られた場合に限られる。プロジェクトオーナーの立場になって考えればよくわかるだろう。

となると、日本の多くの開発現場では「必要最小限」のドキュメントはウォーターフォール開発のドキュメントを簡略化する方向に向かうはずであり、実際そうなっている。

つまり、アジャイル時代でも多くの環境においては、これまでほどではないにせよ、コードに対する説明責任を果たすための、それなりのドキュメントが必要なのだ。

紙やページに囚われる不合理

では、アジャイル時代の文書作成に求められるものは何だろうか?

いうまでもない。変更・参照の容易性だ。

その一方、これまでよりずっと重要性が低くなるのは印刷である。継続的、反復的な開発において、それぞれのイテレーションにおける文書をすべて紙で保持するのは不合理だからだ。

もちろん、紙には印刷しないが、PDFで出力するというプロジェクトも多いだろう。しかし、ページに囚われることで、ページの幅や高さに情報を収めるという制約が発生する。

例えば、第1版でギリギリ1ページに収めることができた表に対し、第2版では新たに列を加えなければならなかったとする。アジャイル開発ではよくあるケースである。こうした場合、何らか対策はあるだろう。しかし、その対策を考えたり、実際に作業したりする時間はどんな価値を生んでいるだろうか?

そのPDF出力が本当に必要かどうか、プロジェクトオーナーと一度よく話し合ってみてはどうだろうか。

Excelはアジャイル時代のための文書作成ツールである

紙出力やページレイアウトを考慮しなくてよいのであれば、Excelの致命的欠点は消滅し、技術文書作成の有力な候補となる。変更・参照が容易なドキュメントを作成するための特性と豊富な機能を備えているからである。

Excelを使ったアジャイルな技術文書作成

本シリーズでは、まず技術文書作成にExcelを用いた場合のメリット・デメリットを整理する。

次に、メリットを最大限に引き出し、デメリットを抑えるノウハウについて以下の順で説明していく。

  • 総論
  • 表・リスト
  • 図作成の実例(シーケンス図など)

References
1 そのほとんどは、酷いフォーマットの文書、そしてそのフォーマットを使わざるを得ない自身の境遇への不満表明であったり、逆に使わずに済む境遇のエンジニアによるマウントに過ぎない。
2 きっと優秀なエンジニアなのだろう

Posted by urojima