継続的ドキュメンテーション

まとめ: まだ色んな解釈がある

ペパボ1（インフラ）

システムとドキュメントの乖離をなくしたい

そのために「構造化データ」をつくって、そいつからシステムとドキュメントをつくる（関連付ける）ようにする

ペパボ2（社内形式知化）

修正しやすい（修正依頼を出しやすい）ラッパーを設置することで（修正数が上がり）ドキュメントの品質が上がる

GitHub markdown repoをラップしたビューワで、修正提案と修正者へのSlack通知がメイン、ゆえに修正が回りやすい

infoQ記事Omer Rosenbaum氏（ソフトウェア）

あるファイル内のコードを読んでいて、そのコードについて説明した関連ドキュメントを参照する、ということが可能

あるコードに対する説明へのアクセシビリティおよびその説明のクオリティ

問題提起だけ

LIFULL（ソフトウェア）

正式なドキュメントの前段階の「エンジニア達だけが見るメモ」を、GitHub Discussionsでつくる

Discussionsなので議論とか投票とかできる

sta.icon

-.icon

ggr

自分自身の書いたものではないコードを構築、確認、変更しなければならない場合、開発者には、コードの機能や背景、根拠などの理解を支援するドキュメントが必要です。ドキュメントがあれば、リバースエンジニアリングをしたり、知っているかもしれない人を探してスレッドやチャネルを探し回ったりして、時間を浪費する必要はなくなります。

多くのものを一気にドキュメント化しているのです。そのため、ドキュメント作成は次第に後手に回るようになり、ついには開発が終了して未完成のまま残されます。

だから最初から継続的にドキュメントつくっていこうぜ →継続的ドキュメンテーション

原則３つ

常に最新である

最適な時に作成される

例えば、大規模な機能が完成した時や、重大なバグが解決した時などは、他のコード開発担当者もその内容を知っておくか、理解しておく必要があります。この時点であれば、開発者の記憶も鮮明で明確ですから、ドキュメントを作るのもずっと容易なのです。

コードと一致する

例えば、あるファイル内のコードを読んでいて、そのコードについて説明した関連ドキュメントを参照する、ということが可能になります。

アプリケーションやインフラの変化にドキュメントは追従できているでしょうか？……発表者は開発の現場におけるドキュメンテーションの継続性・持続性の実現について関心があります。

落選してるけど

開発者新規メンバーが開発できるようになるまでのインプット、としてのドキュメント

アプローチ色々整理してる

コードから構造化データを切り出す

構造化データからコードとドキュメントをつくる

複数使う感じだな

tbls

ndiag

https://gyazo.com/0c8c48325aa84958f5c37f3d305a09a3

構造化データを介して関連させる

なるほど

まあそうなるか

ペパボで働く人々には「書く」という行為が定着しています。現在利用中のサービスを見渡してみると、GitHub、Slack、Google Docs、Scrapbox、Notionなどがあり、常に積極的な読み書きが行われています。

そういった「書く営み」をいかに体系化するか

アンケ撃って、まずはこうしようとなったらしい

社内の全員が知っておくべきことで、知らないと不利益が発生してしまう類のものは、すぐに見つかるようにする

つまり

GitHub Markdownベース

Webアプリとしてラップして、主に提案機能+Slack通知を提供することで「気軽に修正依頼」「適切な修正者に通知」を実現

継続というかlean documentationって言葉だけど

ドキュメンテーションを成功させるために、最も重要でかつ最低限必要なことは「（継続的に）読まれること」である……文書が適切に書かれるから読まれるのではなくて、読まれるから適切な形に変わっていく。読まれなければその文書は死んだも同然である。

ドキュメンテーションとはコミュニケーションであり、その質にはコミュニケーション能力がそのまま反映される。だからこそプログラミングそのものよりも難しいと言っても過言ではないように思える。

いかに読ませるか

そしてそれはコミュニケーションの領分に他ならない

sta.icon