blog

主にJavaScriptを書いています

ドキュメントを書く技術

READMEを始め、ソフトウェアのドキュメント全般を書く技術というものをもっと洗練させていきたい。要件定義書のようなものだけでなく、開発方針や設計方針、API定義などなど。

これらのドキュメントをしっかりと整備するだけで、レビューの質も上がり新しい人が入ったときもスムーズに意識のズレなく開発ができる。はずだが、なかなかドキュメントの上手い書き方や管理の仕方というものは、コーディングのそれとは違い議論が活発ではない。

最近試してみたこと

そういったドキュメントの中でも、"開発方針"や"設計思想"をどう残していくかということを考えている。それらを残しておくことで、コーディングのときも立ち戻る場所ができ、大きく道を踏み外さなくなる。

例えば、レイヤードアーキテクチャのようなものの"境界"をドキュメントにしていく。MVCでもクリーンアーキテクチャでも何でも良いけど、それらのアーキテクチャではそれぞれのレイヤの役割は定義されているものの、必ずしも理想通りにいくとは限らないし、理想を追求することだけが正ではない。そういったアプリケーション・組織独自の"境界"をドキュメントに残していく。

個人的に各レイヤ(controllersやmodelsといったディレクトリ)にひとつずつREADMEを置いていくのが好きなのだけど、最近はそこに「MUST(MUST NOT)」、「SHOULD(SHOULD NOT)」、「MAY」などを書くといいのでは?と思って書き始めている。

# Controllers

## MUST

- ファイル名はXXXControllersとすること
- メソッドはGETならfindXXX、POSTなら....
- このレイヤでリクエストパラメータをxx型に変換する

## SHOULD

- ビジネスロジックは書くべきでないが、xxxなケースは例外とする

MUST/SHOULD/MAYの表記などはRFCでも使われていてエンジニアには比較的馴染みがある(?)はず。READMEに書いてあればレビューも通せるし、新しくプロジェクトに入った人がドキュメントの場所がわからない、ということもない。

ドキュメントの再現性

設計指針というものは、人によって判断がわかれる"迷い"から生まれると思っている。だからこそ、その迷いが出た時に「これはControllerのSHOULDじゃないの?」みたいに一種のフレームワークに当てはめると考えやすくなる。

ドキュメントを書く技術というのは、同時にドキュメントを"書かせる"技術でもある。コーディングと全く同じで、自分だけが書けても意味がなく、誰が書いても一定のレベルにすることが重要。そのためにはフォーマットを作ったりドキュメントの目的を共有したりして、適切な"枠"から無理なくドキュメントが生まれる環境を考えていきたい。