最近 hitode909 さんが、ここ最近ドキュメントについて書いているのを読んで、
- Creating Documentation in an Agile Scrum Environment
- チームのScrapbox3000ページくらいを見返して整理した
- The Product is Docs: Writing technical documentation in a product development group
そういえば、Increment が Documentation 特集だった号 があったなあと思い出したので、読んでみた。
Increment は Stripe のやっている雑誌 (という話は2017年にも書いた)。もともとはオンライン雑誌だったのだけど、今は紙版も売っている。といっても Airbnb Magazine や Offscreen のように、実際に本屋で売っていたりはしない、と思う。
一番よかったのは、Stripe の documentation manager の人の Why it’s worth it to invest in internal docs で、
- Yes/No と自由記述のコメントで顧客満足度を調べよう
- ドキュメント全体のうち、ちゃんとメンテナンスするものを決めて、目次をつくろう
- 個々のドキュメントに「オーナー」を決めて、オーナーに求めることを決めよう。オーナーが退職するときは、次のオーナーにちゃんと引き継ごう
- 昇進のときにも、コードだけではなくて、ちゃんとドキュメントを書いているかどうかを評価しよう
トップダウンでのがんばりは要求されがちだけれども、実践的で参考になる。
次点で、A primer on documentation content strategy と、Python の機械学習 NLP ライブラリのドキュメントの改善について書いた The process: Transforming spaCy’s docs も面白かった。