開発者が開発を進めているときに大事なことは、できるだけ本業の開発に専念できる時間を増やすことだ。

本業の開発時間を確保するのに役立ってきたこと

• ソースコードの管理コストは、バージョン管理ソフトウェアで改善した。

 

• タスクの管理コストは、課題管理システムRedmineなどで改善した。

 

• 　これによって、発生しているトラブルの状況を何人もにそのつど説明しなおす手間が減った。Redmineにチケットを発行して、そのつど状況を書いてしまえば、細かい状況をきれいさっぱり忘れてしまえる。

 

ソースコードのドキュメンテーションをMS-Wordで作るのではなく、Doxygenを用いてドキュメンテーションコメントからドキュメントを自動生成させる。このことでドキュメントを別に作成するというコストを改善した。

そして、残っているコストには、ドキュメンテーションコストがある。
Word、PowerPoint、Excelなどでドキュメントを書く（もしくは書かされる）コストだ。
結果を示す画像データがフォルダにあるのに、それをPowerPointにスライドになるようにコピー＆ペーストする（もしくはさせられる）コストだ。

ドキュメンテーションコストの特徴

• 画像・グラフ・表などを作成して、PowerPointのスライドなどにコピー＆ペーストを手作業でする。

 

• 計算にやり直しがあると、ドキュメンテーションは全て手作業で繰り返さなくてはならない。

手作業で行なうので、いくつかの図面が更新もれを生じやすい。

データ処理のプログラム（もしくはスクリプト）と、そのドキュメントとの関係が自明ではない。

「あれ、どうやってこの図を作ったんだっけ？」
自分が作ったプログラムとドキュメントを、別なデータで他のメンバーに作業してドキュメントをまとめてもらうのは簡単ではない。

Excelの場合だと、テータと手順の部分とが区別されていないため、入力データを差し替えて処理をするのがわかりにくい。

ドキュメントでは多数の手作業があり、ちょっとした条件の変更のたびに何度も繰り返さなくてはならないことがある。ドキュメントを作り直すときに多くの時間を必要としてしまう。

せっかく、一連の処理を自動化しているのに、ドキュメントの作成で開発者の貴重な時間を使ってしまっていることは多いのではないでしょうか？

この記事では、そのようなドキュメンテーションコストを下げる方法を述べます。

手法　データ処理の結果をhtmlファイルで出力させる。

htmlファイルを自動で生成させれば、解析結果をまとめる作業を自動化できる。
このような方式を実行している人は多いことでしょう。

手法　Jupyter notebook 環境を使う。

Jupyter notebook 環境(かつて IPython Notebook 環境と呼ばれていたもの)では、web上でipynbファイルを表示します。そのセルに、コードを記入し、そのセルを実行させると、セルの実行結果がその直後に表示されます。

セルの種別をMarkdownに選んでおけば、その部分はMarkdown言語として解釈されて表示させることができます。

そうすることで、実行できるドキュメントとしての環境が用意されています。Python言語の場合、Jupyter notebook でサポートしている代表的な言語です。詳細は以下の記事にまかせます。

Jupyter事始め

現在（2016年12月時点）ではPython、Julia、R、Ruby、Haskell、Scala、node.js、Go、Luaなどの言語に対応しています。

Jupyter notebook によって減らせるドキュメンテーションコスト

このように、実行できるドキュメントで結果をまとめあげることにすれば、上に書いていた課題が解決できます。

• PowerPointのスライドなどにコピー＆ペーストを手作業でするのではなく、Jupyter notebook のファイル(*.ipynb )で [Cell] [Run All] とした結果がドキュメントそのものになります。

 

• 計算にやり直しがあると、ドキュメンテーションは[Cell] [Run All] で実行しなおせば十分です。

手作業で図を作ることはないので、図面が更新もれは生じません。

データ処理のプログラム（もしくはスクリプト）と、そのドキュメントが*.ipynbファイルで一体化しているので、関係は自明です。

「あれ、どうやってこの図を作ったんだっけ？」とはなりません。
自分が作ったプログラムとドキュメントを、別なデータで他のメンバーに作業してドキュメントをまとめてもらうのも、その*.ipynbファイルを実行してもらうだけです。

pdf ファイルの出力でのドキュメントの確定
web ブラウザ上で[file] [print] で出力先をpdf にして出力します。そうするとpdf ファイルを受取った側はjupyter notebook 環境がなくても結果を読むことができます。

実行結果のドキュメントとしてのjupyter notebookのipynbファイル

ipynbの拡張子には２通りある

• セルの実行結果を含む前のipynbファイル

 

セルの実行結果を含むipynbファイル

バージョン管理する目的ならばセルの実行結果を含めないipynbファイルにするのがいい。実行結果を含んでいる状況から[cell] [output] [clear all]すればセルの実行結果を含まない状況になる。

一度cellでrun all を実行すれば、セルの実行結果を含むipynbファイルになります。
Jupyter　notebook がインストールされている環境ならば、セルの実行結果を含むipynbファイルを開けば、それまでに実行した結果を含むドキュメントとしてよむことができます。ですからあなたが実行した結果のipynbファイルを別の人に送って、jupyter notebookで開いてもらうと、あなたのマシンで既に計算した結果が表示できます。
この点もドキュメントを共有するという意味にそったものになっています。

Jupyter notebook がもたらしたもの

• そのまま実行できる手順書

 

• そのまま実行できるチュートリアル

 

簡単に更新できる実験レポート

将来の参加メンバーが困らないためにも

• git, SVN でソースコードを管理する。

 

• 必要なシステムの構築手順もバージョン管理する。

 

• 電子メールではなく、Redmineなどのシステムで課題管理する。

 

スクリプトの実行と結果のドキュメントの作成を別物にするのではなくて、Jupyter notebook のようにスクリプトとドキュメントが一緒になった環境の利用もしてみる。

補足

ipynb ファイルとpyファイル

ドキュメンテーションの用途にはipynbファイルを使うけれども、全てのスクリプトをpyファイルにする必要はない。私の場合は、ipynbファイルにするのは、ドキュメントとして表示させるための部分だけにしていて、大半の処理は通常のpythonのpyファイルのままにしています。

ipynb ファイルのバージョン管理

ipynb ファイルの実行結果をclear した状態でsave しておいて、その状態でバージョン管理ソフトでcommitする。そうすれば、少ない差分の状態でバージョン管理できる。

---

IPython notebook という名前を使っていますが、Jupyter notebook のことです。

これらの本はいずれも、ドキュメンテーションコストが下がることを指摘しています。

追記：管理コストを下げることは価値を生む。

コインパーキングがいたるところにある。
むかし、駐車場に管理人がいる時代には、駐車場の管理コストのために、少ない面積だと駐車場として運用できなかった。
しかし、無人化して運営できるようになったことで、少ない面積のスペースがコインパーキングとしてサービスを提供し価値を生むようになった。

同様に、他の分野でも管理コストを下げることは価値を生み出す。
ドキュメントの管理コストを下げることは、価値を生む。
データの登録のためのコストを下げることも価値を生む。
データの登録のためにFAXを送受信することは、無駄なコストを発生させ続けている。

• 書式をワープロ用に取り込む。

 

• その書式でワープロで編集し、プリンタで印刷する。

 

• 印刷したものを、FAXで送信する。

 

• 受信したFAXを人が読み取り、データベースに登録する。

 

（データの未登録・データの重複の登録が生じないようにするチェックが必要）

そういった状況の中では、最新の状況を把握するのに、現場の貴重な労力を奪ってしまっている。