Doctective

Doctectiveは、厄介な一つの問題を中心に作られた開発者向けツールだ。コードは絶えず変わるが、ドキュメントは変わらない。誰かが関数名を変え、設定フラグを変え、endpointを書き直すと、その挙動を説明するドキュメントは静かに古くなる。誰かが丸一日を無駄にするまで、誰も気づかない。

Doctectiveはそのずれを監視する。コードベースとドキュメントをインデックス化し、両者の間に意味的なリンクを張る。あるpull requestがドキュメントの参照しているコードに触れると、ツールは影響を受けるページを指摘し、更新案を載せた相棒PRを起草する。承認はすべて自分で行うが、最初の一巡はすでに済んでいる。

適用範囲ははっきりさせておく。Doctectiveはソースコードとドキュメントを読むので、開発ワークフローの中に住んでおり、マーケティングサイトや顧客向けwikiではない。チームがGitHubを使っていないなら、たぶん対象読者ではない。

では、ドキュメントが散らかった人にしか役立たないのか。そうでもない。規律あるチームでも、一度のリファクタリングで古い挙動を説明するページが3枚残ることはある。

はじめ方

1. doctective.appにアクセスしてGet Startedをクリックする。これでGitHub接続が始まる。
2. Doctective GitHub Appをインストールし、監視したいリポジトリへのアクセスを許可する。
3. インデックス化するrepoを選ぶ。Doctectiveはすぐにコードとドキュメントの間に意味的なリンクを構築し始める。
4. いつも通りpull requestを開く。ドキュメント化されたコードに触れると、DoctectiveはそのPRにコメントし、ドキュメント編集案を載せた相棒PRを開く。
5. 提案された変更を確認し、必要なら文言を調整して、残したいものをマージする。