Design Docの話を書いていて思ったが、自分はそれよりもWikiとかインフォーマルなドキュメントを書く方が好きなんですよね。 という事でその辺の話を書いてみる。
Wikiに何書いているの？
Wikiはインフォーマルにいろいろ書いていて、インフォーマルゆえに「これ」というのは難しいのだけれど、 皆が何書いているかを知りたいので自分のやっている事もなんとなく言語化してみる。
コーディングにまつわる、直近のTODOの書き出し
まずやらなくてはいけない事が複数あってなんか手が動かない、みたいな時に、やらなきゃいけない事を箇条書きで書き出したりする。 箇条書きに書き出して、それを眺めて考えたり、散歩してきたりして、やらなきゃいけない事を考えていく。
自分の場合、何か手が動かない理由の半分くらいは何をやるかが自分の中で明確になってないケースなので、 そういう場合はWikiに書き出してそれを眺めて考える、というのは結構有効に機能している（そうじゃない場合は結局手は動かないのだけれど）。
簡単なものはローカルのテキストファイルに書いているのだが、手強い物で考える必要があるものをWikiに書いて考えている気がする。
曳光弾にまつわる事
何を作りたいかが曖昧で、いわゆる曳光弾を打つ時にもよくWikiを書いている。 何が曖昧なのか、よく分からないと思っている事はなんなのか、をぼんやりと書いて、 その辺をもう少しマシにする為こんな感じの曳光弾を打とうと思ってる、とか書く。 で、実際に実装していく過程で考えてたのは全然違っていて、実際の曳光弾は全然別の物になって、分からないと思っていた事や曖昧と思っていた事も全然違う所が曖昧だった、 みたいな事が判明したりするのだが、そういう事も追記していく。
あと実装が終わったあとにどうだったか、は良く書いている。分かった事、新たに生まれた分からない事、当初考えていた事がどこが間違いだったか、など。
最初に思っていた事はだいたいいつも間違いなのだが、最初に書いた事は訂正はせずにそのまま残している事が多い。 あとに追記した事だけでは意味をなさず、でもその前の記述は間違っている、というような状態にはなりがちで、これについては歴史改変のあたりで後述する。
自分マイルストーンにまつわる事
やろうとしている事が壮大過ぎて何から手を付けていいかよく分からない、という事がある。
そういう時にはやりたい事を適当に分割した、自分マイルストーンを勝手に定義して、それにバージョン番号を降って開発を進めていく。 Ver 0.1ではXXXをやる、Ver 0.2ではYYYYをやる、みたいな事をだらだらと書き出す。 次にやる事はまぁまぁ詳しく、次の次にやる事はぼんやりと、その先は妄想みたいなのが一行書かれてるだけなのが並ぶ、みたいな形が多い。
始まりは前述のTODOの書き出しの一種だが、その後各自分マイルストーンのサブセクションが成長していく所がちょっと違う。 また各バージョンと先述の曳光弾との違いは曖昧。
自分マイルストーンはチケットも切って、Wikiとは相互リンクを貼っている。
壮大な事はだいたいうまく行かないので、なんでうまく行かないのか、みたいな記述が増えていって当初考えていたところまでたどり着かず、どこかでピボットする事になる、というのもありがち。 そういう軌跡が曖昧に残る感じになる。
設計的なこと
設計的な事を書く事もある。ARCHITECURE.mdみたいにあとから書く事もあるし、 作る前になんとなく思っている事を書き出す事もある。 レイヤリングとか、本当はこうしたいんだがこういう理由でこうしている、といった言い訳とかそういうのも書く事はある。
基本的にはソースコードやコメントやコミットログやUnitTestで設計意図は読み解けるように書いているつもりで、それが望ましいとは思っている。 特に設計的な事はなるべくコメントに書くようにしている。
でもWikiにも書いてあるな。どう違うんだろう？ Wikiはファイルをまたがる全体的な事や補助的な情報を書いている気がするが、今見直すとdoc stringに書く方がいいな、と思う事もある…
feature flagとか技術的に知られているイディオム的な解説
何かを実装した時に、それが業界で良く知られたアイデアに基づいている事がある。feature flagの仕組みとか。 そういう、実装した事に関わる、一般常識ではあるが知らない人も居るような背景知識を、Wikiで解説したり、further readingを紹介したりする。 また、参考にしてはいるが違うものになっている場合は、その理由というか裏話的な事も書いている。
調査関連
調査する時はWikiに調査する内容とか調査のモチベーションとか読んだ記事とか動画とかのリンクとかを書いたりする。調査はissueにする事もあり、その辺の使い分けは曖昧。 外部技術に関する調査で公式ドキュメントとか動画を読んでいくようなのはWikiが多いかなぁ。 逆にパフォーマンス調査とか自分たちのコードベースの特定の側面とかを調査するものはissueにする事が多い。issueとの使い分けについてはあとでも触れる。
karino2 on software
何か意見を言ったり何かフィードバックを返す時に、背景が膨大で全部その場では説明出来ない、という事がある。 例えばslackでバグの報告とか質問があった時に、Issue trackerに上げてもらう。 そういう実際の行動はその場でお願いしたりすれば良いのだけれど、何故そうした方がいいのか、というような背景とかについては、 その場ではあまり説明出来ない。
そういう時に、そもそもIssue Trackerを使う意義とは何か、とか、どういうissueの記載が望ましいのか、とか、 そうした背景の説明をエッセイとして書くというのをやっている。
そういう「直接はチームの決定には関係しないが、背景となるようなソフトウェア開発に関わるエッセイ」は、 Joel on softwareオマージュとしてkarino2 on softwareというタイトルにしてWikiに書いている。
この手のエッセイは、全員に読んでもらう事は期待してない。ただし何かをslackで説明してる時などに必要になったらリンクを貼る事はある。 だいたい読んでほしい人は読んでくれないが、関係ないチームの若者とかに人気になったりする。
未実装なモジュールのモックアップとして
相互に依存するモジュールがあって、片方が無いともう片方が考えられない、みたいな事がある。
例えば、Domain SpecificなBitCodeとVMを設計したい、みたいな時（Domain側の知識は十分にあるとして）。 BitCodeの設計がVMの構造を決め、VMのロードとか実行時の構造がBitCodeの設計を決める、みたいな相互依存があり、 でも最初に両方を一気に考えるにはそれぞれ手強くて難しい。
こういう相互依存があってどちらもそれなりに大きい時は、片方、例えばVM側を、自然言語で曖昧に書いた物で代用して、BitCode側のコーディングを進めたりする。 まずVMについてぼんやり思っている事を言葉にして書き出す。 それを元にBitCode側を考えながらコンパイラを書いていく。
こういう時には、ぼんやり思っている事はだいたいちゃんとは言葉に出来ないので、文章が途中で止まる。 例えば以下みたいな日本語の途中で止まった文章が書かれる。
このVMの基本構造はスタック型マシンである。ただしfor文の所では
ここまで書いていたら、良くわからなくなってきた、という時に、文章の途中で止まる。
こういう良くわからなくなった所で止めておいて、そこまでを眺めて考えたり、とりあえず分かってる範囲の知識を元にBitCode側のコードを書いてみたりする。
両方がある程度出来てくればコーディングの中でデザインを行っていく方が良いと思うけれど、最初のブートストラップとしてハリボテを作るのにインフォーマルな自然言語はなかなか良い事がある。
図を含めたコードのコメントの代わりとして
コードのコメントで図を含めたい時に、その代替としてWikiに図入りの説明を書いてリンクをコメント側に入れたりする。 ただWikiは失われてコードが残る事は（残念ながら）良くあるので、コード側だけでも理解出来るようには気をつけている。
準時系列とか更新の話
実態と合わなくなった情報をどう扱うか、みたいなのはインフォーマルなドキュメンテーションで割と重要なトピックと思うので、 自分がどうしているのかの話を。皆はどうしてますかね？
準時系列な追記と、staleになるメカニズム
「自分マイルストーン」の所とかでも書いたけれど、 自分は、項目ごとに時系列に追記していくスタイルで書いているものが幾つかある。
セクションは時系列じゃないんだが、サブセクションは時系列に追記していく、みたいな。 そうした時系列に追記していく物は、基本的に前に書いた事と、あとに書いた事に整合性が無い。
例えば何かを書き出して、それに基づいて実装をすると、書き出した事の勘違いに気づいたりする。 そういう時に、その勘違いをWikiには反映させずに、その次に詰まった時に詰まった事とかをWikiに書く。
すると詰まった時点での理解を元に追記された内容と、その理解の以前の良く分かってない時に書いた考えている事はつながらない。 こういう時に、「基本的には」前に書いてある誤りは直さない事にしている。
更新や歴史改変とその方針
基本的には前を直さずに追記をしていくのだけれど、一定まで行くと問題が出てくる。
目に入れて考える時に、間違った事が多すぎるとかえって考える邪魔になってくる。 残す情報としても、実態と乖離している割合が多すぎて、かえって有害だな、と感じるようになる。
そういう時は、多少手を入れている。 手を入れる方針としては、時系列的に一番最後の内容がちゃんと意味をなすように、そこと関連ある場所だけ遡って直す、という事をしている。遡って直すのを歴史改変と読んでいる。
例えば「XXXを考えてYYYという作業をやる」という記述があった時に、「XXXを考えて」を、当時は実際には考えてなかったがあとに分かった事に直したり、当初考えていた間違った所を削除したりして、続きの追記内容とのギャップを無くす。その代わり、そのブロック内での整合性は無くなって事実でもなくなる。だが、全部をちゃんと直すのは面倒で続かないので最後の記述以外が変になるのは受け入れている。
こうする事で、たまにその時点での正しい記述になるチェックポイントのような物を設けている。 ある日何らかの理由で突然更新しなくなっても、割と最後の方の記述は意味を成すように出来る。トラックナンバー的な考えですね。