目次
はじめに
PLATFORM ENGINEERING KAIGI 2024のアーカイブを観たので、個人的にためになった話をまとめていきます。今回は『明日から始める持続可能なドキュメンテーション戦略: Documentation as a Product』についてです。アーカイブは以下です。
役立つかもと思ったら動画をぜひ観てくださいね。
ドキュメンテーションの課題感
とてもわかりみが深い。たとえば以下は私の組織でもいえそう。
- 必要なドキュメントにたどり着けない
- 古い
- 品質がバラバラ
やっぱどこも同じようなことで悩んでますね。ドキュメントの品質が低くても、急にシステムが止まったりするわけでもないので、けっこう腐りやすいという特徴がドキュメントにはありそうです。そんなことをあらためて思いました。
品質の高いドキュメントとは
大前提として継続的な改善が必要というのはあるとして、品質の定義を以下のように整理していました。完全に同意。最近機能品質と構造品質というのがあって、前者の方がまず大事だよね、みたいな話がちょうど出てきたところです。
| 項目 | 説明 | 優先度 |
|---|---|---|
| 機能品質 | ドキュメントの目的やゴールが達成されているかどうか | 高 |
| 構造品質 | ドキュメント自体がうまく書かれているか、うまく構成されているか | 低 |
ドキュメントの高い品質を維持するには
どれも参考になりました。具体的にどう進めていけばいいのかという話です。
作成フェーズ
- 機能品質
- ドキュメントタイプを定義
- ドキュメントタイプごとに想定読者・ゴールを定義
- 構造品質
- テンプレートを用意
レビューフェーズ
- 機能品質・構造品質それぞれについてのチェックリストを作成
- レビューフローを作成
運用フェーズ
| 指標 | 低下を判断する方法 |
|---|---|
| 鮮度 | ・最終更新日から一定期間 ・メンテナー不在 ・デッドリンクあり |
| 有効性 | 閲覧されていない…など |
これらの指標が悪化しているドキュメントは、APIなど可能な限り自動でピックアップできたら嬉しいですね。あとは実際にメンテナンスしていこうという感じです。週に1回30分など時間を区切って対応しているそうです。
さいごに
どこのチームにいっても役立ちそうないいお話がきけてよかったです。
コメント