ポエム
ドキュメント
asciidoctor
エクセル
RedPen

エクセルで手順書を作るのはきっとやめた方がいい

More than 1 year has passed since last update.

追記(2017-01-05)

「エクセル 手順書」でググったら上の方にくるようになったのですが、その検索結果ページには業務手順書をエクセルで作るとかそういうのがあり、なかなかカオスです。

あとから見ると主語が大きい気がしたので、すこし補足をいれます。あくまでエンジニア業界で、特にソフトウェアのインストールや、サーバの環境構築などの手順書にはエクセルは不向きなのでは、という実体験に基づいたお話です。


ある製品のインストール手順書を作ることになり、参考資料として過去の案件で作ったものをもらったのだが、それはエクセルファイルだった。

どういうものだったかを端的に述べると以下の通り。

  • 目次がない
  • シート名に番号はついていない
  • 各シートにも番号の記載はない
  • 各シートの中身はスクリーンショットの羅列
  • スクリーンショットについての説明がほぼない
  • 間違った手順のスクリーンショットも混ざっている
  • 操作の結果を確認する手順が漏れているケースがある

この時点で大分げんなりするが、具体的に辛い点をあげる。

1. 全体像が掴めない

目次がないので、インストールに必要なものや作業のボリューム感が掴めない。
シートの枚数や、それらにざっくりとつけられたシート名からでは無理だ。

2. 順番に確信が持てない

目次がなく、シート名にもシート内にも番号がないので、左端のシートから順にやるしかない。しかし、どういう理由でその順番に並んでいるかの説明もないので、正しいと信じられる根拠がない。

例えば、「Aをインストールする際にDBを使うから、その前にRDBMSをインストールする」といったような、その順番である理由が書いてあればあっているかどうかの判断材料になる。そういったものがなければ、最後まで問題なくいったときにしか合っていたと思うタイミングがない。

極端なことを言えば、誰かがシートの順番を誤っていれかえたらそれだけで破綻する状態なので、疑心暗鬼になりやすい。

3. コマンドの内容やインストール先のディレクトリもスクリーンショットに埋まっている

例えば、「zipファイルを展開してその中にあるインストールスクリプトを実行」というのはCLIのみで完結しているので、そのコマンドを手順書からコピペして使いたくなる。でも、そういう手順もスクリーンショットでになっているので、拡大して読み取って手打ちせざるを得ない。目も心も疲れる。

4. インストールがうまくいったかの判断材料がない、それを見つけられない

バージョンを表示させるコマンドを実行したり、特定のURLにアクセスするなどの動作をさせることで、インストールがうまくいったかを確認するのが通例である。しかし、その手順もスクリーンショットになっていて、何を確認するかもわからないし、それが確認のためのものであるという説明もない。ひどい場合は、そのスクリーンショットすらもない。これでは、作業が終わったかどうかすらもわからない。

5. 再利用できない

スクリーンショットの羅列なので、ファイルをコピーしてそれをもとに作り直すことによるメリットがほぼない。このやり方では、結局はスクリーンショットを全部差し替えることになるので、シート追加の手順しか省けない。しかもそうして作ったものは、手順書としては非常にわかりづらいものになるので、新たな犠牲者を増やすだけ。作る側も、手順に対する理解も深まらない。

6. 修正したときに差分がわからない

修正は、実質スクリーンショットの差し替え(あるいは、追加・削除)のみになる。エクセル自体もgitなどで差分を追うのが困難なのに、どのスクリーンショットをどういったものにかえたかとなると更に無理そう。

7. レビューするのが困難

目次もないし、内容がスクリーンショットに埋め込まれているので、手順に抜けがないかや正しいかをチェックするのが面倒。指摘も「どこそこのスクショを差し替えて」にしかならないので、レビュワーとレビュイーのモチベーションが維持できそうにない。

まとめ

エクセルによる手順書は、作る人もそれを読む人も、誰も幸せにならない。災いの種、諸悪の根源である。「インストール作業中に適当にスクショとって、それをエクセル貼り付けるだけの簡単なお仕事」では、手順書にならない。

エンジニア向けのライティングの到来

markdownで書いてGitHubで管理、というのも出したが、それにCIもからめたものもどんどん出てきている模様。次のような本も出るのも、その流れが大きくなっているという証だろう。

ドキュメント作成システム構築ガイド[GitHub、RedPen、Asciidoctor、CIによる モダンライティング] 単行本(ソフトカバー) – 2016/3/25

http://asciidoctor.org/

http://redpen.cc/

継続的インテグレーションで実現するWebメディアの執筆フローのように、ライターの人の作業にも、GitHubとCircleCIを組み込む例も。

エディタを自作するケース

完全に単一のHTMLファイルで動作するMarkdownエディタ作った にあるように、納品を考慮して単一htmlファイルで済ませられるエディタもでてきています。

https://github.com/tatesuke/KanTanMarkdown

参考サイト

蛇足

誤解がなければいいですが、エクセル自体には罪はないと思っています。表計算ソフトとして使う分には問題ないですし、そういう用途で自分も使っています。
(坊主憎けりゃ袈裟まで憎いというので、憎しみが全くないとは言い切れないですが・・・)