モチベーション

ソフトウェア開発においてドキュメントはコードの一部であり、ユーザにとっては機能の一つだ。特に開発者用のソフトウェアやシステムを開発している場合、ユーザがそれらを使える、あるいは使ってみたいと思うかどうかは質の良いドキュメントに大きく左右される。そんなことは誰だって解っている。それでも、長年社内向けのソフトウェアやシステムを開発してきたが、ユーザにとってわかりやすいドキュメントを継続してメンテナンスしていくのは想像より遥かに難しい。

思うところあって、開発者用のソフトウェアの良いドキュメントを書く技法について研究しているのだが、Docs for Developers という本がドキュメントの構成の仕方から、ドキュメントの品質計測方法、長期的なメンテナンス方法まで網羅していた。自分が抱えていた問題を解決してくれそうな手法を本著から抜粋しながら考察していく。

本の概要

本著は SaaS を提供しているチームがユーザである開発者向けのドキュメントをゼロから構築していくプロセスと技法が紹介されている。前半は、ユーザが求めるドキュメントをどのように構成すれば良いのかを分析、分類、構築していく。後半はドキュメントの品質を計測するために有用な指標、などに触れながら、リリース後のドキュメントを継続的にメンテナンスする方法について解説している。

本著の使い方

本著は辞書的に使えるものの、構成は前章の内容を引き継いでいるものとなっている。従って、一回は1章から最終章まで通読したほうが良いと思う。幸いページ数は多くない。一度読んでしまえば、新しいドキュメントを書くのにも使え、既存のドキュメントを改善していくのも使える。

各章のメモ

自分が抱えていた問題へのアプローチ

ドキュメントを書くときに個人的に

Problem Category Approach Probability to be solved
ドキュメントの構成に迷う Structure&Style
ユーザにとって有益なドキュメントになっているかわからない Impact
ドキュメントを更新する人が同じ人になりがち Maintenance
共通で開発してるドキュメントのストラクチャーを強制する Structure&Style
更新されていないドキュメントがある Maintenance
ドキュメントにタイポがある Structure & Style
ドキュメントの英語表現に一貫性がない Structure & Style

ドキュメントの構成に迷う

問題背景

アプローチ

所感

ユーザにとって有益なドキュメントになっているかわからない

  • オンボーディングマニュアル
  • 開発環境の構築
  • 採用試験のドキュメント(準備は期待している時間で終わるか)

ドキュメントを更新する人がいつも同じ人になりがち

オーナシップを明確にし、同じ人がに偏らないようにする工夫する。

Cognitive Load の検知はどうすればいいのか?

共通で開発してるドキュメントのストラクチャーを強制する

みんな違う場所にあるとわけわからないドキュメントが出来上がる。

更新されていないドキュメントがある

最終更新日を元に 6 months cycle で更新の依頼を自動化する。 ドキュメントのオーナーを決める。

形骸化しないためには同じ人がオーナーにならないようにする必要がある。 = 一人が受け持てるドキュメントの数には限界があるのでどうしているのだろうか?人の数で解決するのか、あるいは別の仕組みがあるのか?

スタイルが開発者ごとにことなる

イギリス英語とアメリカ英語が交じるのが気持ち悪い

Typo の修正

事例(他のarticle でも良さそう)

実際は

とにかく蓄積するところから初めてもいいと思う。 ある程度時間が経ってからドキュメントの全体のリファクタリングをしてユーザが使いやすいドキュメントを作るのが良いと思う

ドキュメントにここまで時間を捧げるかどうかは不明。

複数のチームで一つのドキュメントをメンテする時は?

社内でプラットフォーム、エコシステムがあり同じチームの人だけでドキュメンテーションが簡潔しない事がある。 大枠を共有しておくのはかなり重要だと思う(GitLab の例を見ていきたい)

まとめ

たしかにここで書かれていることを実践できれば品質の良いドキュメントを書くことができそう。一方でチームで開発をしているときに全てのメンバーが一貫性のあるドキュメンテーションポリシーを持つことは難しいと思う。

Docs for Developers: An Engineer’s Field Guide to Technical Writing (English Edition)
  • Author: Bhatti, Jared
  • Manufacturer: Apress
  • Publish date: 2021-09-30T00:00:00.000Z