問題1. 自由記述は負荷が高い vs. 決められたフォーマットは表現力が低い

難しさのひとつは、表現力と利用負荷のバランスです。ブログのように自由に記述できるフォーマットは表現力が高い一方で、その記述の正確さや分かりやすさは書く人の力量に強く依存します。他方で、書き込めるものが制限されているタイトなフォーマットの場合、書く人の負荷は低く、文章の品質もある程度安定しますが、表現力という点では自由記述には劣ります。Fabbleでは、高い再現性を持つことが望ましいレシピには決まったフォーマット、メモには自由記述を採用しています。

問題2. 意図を伝えるにはストーリーが大事 vs. ものの再生産のための情報と背景情報は分けてほしい

プロジェクトの意図を読者に理解してもらうことは非常に重要です。そのためには狙いや思い、試行錯誤の過程、判断の根拠など、さまざまな背景を伝え、ストーリーとして語ることが大切になります。一方でそのプロジェクトの成果物を再現するためには、やるべきことだけができる限り短くまとまったドキュメントが好ましい。プロジェクト内に再現のために必要な情報を書くレシピ、なんでも書けるメモという2つの異なる記述方法の使い分けることでこの問題を解決できます。 

問題3. プロジェクトを始めたときにはレシピに書くことがない

プロジェクトを始めた時には、当然ながら目標となるものを作るためのレシピはありません。ですが、ドキュメンテーションを諦めないためには、プロジェクトの進行と同時に記録を進めることが肝心です。プロジェクトを始めた時に、まずメモで企画と調査について書き、プロジェクトの進行にあわせて工程の比較や判断の根拠を記録していくと、振り返りがスムーズにできるでしょう。