オフィス文書形式が要求されるようなドキュメントではなくて、自分が開発したライブラリのドキュメント（リファレンスマニュアルやチュートリアルなどライブラリのユーザーが読むためのドキュメント）の話です。以下の「ドキュメント」もそのような意味で使っています。
使いやすいライブラリを開発したかったらプログラムだけではなくドキュメントも書くべきです。
なぜドキュメントを書くか
ドキュメントを書く習慣があるかどうかは開発者によってあったりなかったりです。使っているプログラミング言語に相関がある気もしますし、リリースするかどうかに相関がある気もします。理由はいろいろあるでしょうが、ドキュメントを書く習慣のない開発者の方が多いでしょう。
書かない理由はこんな感じでしょうか。
- 面倒。
- 自分しか使わないからいらない。
- どのように書けばよいかわからない。（どのツールを使えばよいかわからない。）
一方、書く理由はこんな感じでしょう。
- 他の人が使えるようにしたい。
- 何度も同じ事を質問されて、個別に説明することの方がドキュメントを用意することより面倒になった。
だいたいあっていますか？しかし、使いやすいライブラリを開発したい場合は「ユーザーの視点でAPIを見直すため」にドキュメントを書くという視点を忘れてはいけません。
ユーザーの視点でAPIを見直す
ドキュメントはライブラリのユーザーが読むものです。そのため、たとえ開発者がドキュメントを書くとしても、開発者の立場ではなく、ユーザーの立場になってドキュメントを書く必要があります。そうしないと「ユーザーが読んでもわからない」・「誰の役にたつのかわからない」ドキュメントになってしまいます。
ドキュメントを書くときはなるべく簡潔な記述になるように意識します。これは「なるべく情報を落とせ」ということではありません。「複雑な説明や長い説明がなくても使えるようにしろ」ということです。
例えば、WebページをPDFで保存するライブラリを作ったとします。もし、以下のようなドキュメントになっていたら要注意です。
まず、WebPrinterオブジェクトを作ります。
web_printer = WebPrinter.new
次にPDFで保存したいURLを設定してWebページをダウンロードします。
web_printer.url = "http://www.clear-code.com/"
web_printer.download
最後に出力PDFファイル名を指定してPDFを出力します。
web_printer.print("clear-code.pdf")
ドキュメントを書いていて「手順が多いな」・「たくさん書いているな」と気付けることが重要です。それに気付いたら「もっと簡潔にドキュメントを書けるようにするにはどんなAPIになっていればよいだろう」と考えてください。これをやるかどうかでライブラリの使い勝手はかなり変わります。
例えば、上述のWebPrinterは以下のように使えるようにすることもできます。
WebPrinter.printにPDFで保存したWebページのURLと出力PDFを指定します。
WebPrinter.print("http://www.clear-code.com/", "clear-code.pdf")
このようなAPIを提供するには以下のような便利メソッドを定義するだけですね。
class WebPrinter
class << self
def print(url, pdf_path)
printer = new
printer.url = url
printer.download
printer.print(pdf_path)
end
end
end
このように、ユーザーの立場で考えて、ユーザが使いやすいものになっているかという視点を意識しながらドキュメントを書くことであなたのライブラリはもっと使いやすいものになります。
まとめ
ドキュメントを書くことがキライな開発者は「ドキュメントを書くよりもコードを書くことに時間を使った方がずっとよいソフトウェアになる」と思っているかもしれません。形だけのドキュメントを書くならたぶんそうなんでしょう。しかし、「ユーザが使いやすいソフトウェアか」という視点でドキュメントを書けば、それはよいソフトウェアの開発につながります。
なお、このような視点でドキュメントを書くとプログラムの改善作業が発生します。そのため、リリース前に慌ててドキュメントを書くとドキュメントもAPIも中途半端な状態のままリリース、あるいは、リリース日の延期になったりします。あらかじめ、ドキュメントを書く時間だけではなく、プログラムを改善する時間も見込んでおきましょう。
参考: Gaucheの開発者のshiroさんも別の視点で見るためにドキュメントを書くというようなことに言及しています。（ただし、「ユーザー視点」というわけではなさそうです。）
