私の仕事柄、公式ドキュメントは日々頼りにしています。執筆の大部分はチュートリアル的な性質のものなので、公式ドキュメントを指針として頼りにしています。公式ドキュメントがなければ、すべてを自力で解決しなければならなくなるでしょう。場合によっては、それもそれほど悪くありません。しかし、公式ドキュメントが絶対に必要な場合もあります。そうすることで、かなり難しいタスクをほぼ誰でも扱えるレベルにまで引き上げることができるからです。
参照:採用キット: Python 開発者(TechRepublic Premium)
問題は、すべてのドキュメントが同じように作られているわけではないということです。そして、この5年ほどで私が学んだことの一つは、公式ドキュメントに頼るのは、朝食を作るのに靴に頼るようなものだということです。
簡単に言えば、靴は調理できず、ドキュメントは役に立たないでしょう。
これは多くのプロジェクト（規模を問わず）にとって大きな痛手です。しかし、公式ドキュメントを使わざるを得なかった経験のある人なら、その苦労がいかに深刻かお分かりでしょう。公式ドキュメントは古くなっていたか、壊れていたり、欠落していたりします。さらに悪いことに、多くの場合、これらの問題を解決しなければならないのは開発者自身です。
ドキュメント化が失敗する理由は何ですか?
これは (貧弱なドキュメントに遭遇したときに) 最初に思い浮かぶ質問ではないかもしれませんが、必ず尋ねる必要がある質問です。ドキュメントがコミュニティで機能しない理由はいくつかあることが分かりました。Kubernetes などの特定のソフトウェアでは、プロジェクトが非常に急速に進化するため、主催者、従業員、ボランティアが対応しきれません。そうなると、最初に見落とされるのはドキュメントです。これは、特に新しいリリースによって以前のイテレーションの機能が壊れる場合に問題になります。Kubernetes の公式ドキュメントに頼らざるを得なかったことが何回あったかわかりませんが、結局は機能しないことが分かりました。このようなことが頻繁に起こるため、公式ドキュメントを参照することすらありません。代わりに、自分で問題を解決するか、製品のユーザーが集まる Mastodon などのサービスを見つけて、そこで問題が解決されている可能性があります。
これが起こるもう一つの理由は、プロジェクトにドキュメント作成を担当する人員が不足していることです。このような場合、ドキュメントは当初は非常に乏しく、時間の経過とともに徐々に充実していきます。しかし、これはアーリーアダプターや、新しいリリースが利用可能になるとすぐにアップグレードするユーザーにとって役に立ちません。
さらにもう 1 つの理由は、プロジェクトのメンテナーがツールを社内使用のみを目的として作成し、ドキュメントの作成に手間をかけず、最終的にソフトウェアを一般にリリースしてしまうことです (最初はドキュメントを書いていなかったことを忘れています)。
これら3つの理由はすべて、私が「ドキュメントの劣化」と呼ぶ状況を示しています。ドキュメントは定期的に更新されなければ劣化し、最終的には使えなくなってしまいます。これは決して容認できる状況ではありません。
優れたドキュメントが重要な理由
簡単に言えば、ドキュメントが劣化すると、ユーザー、管理者、開発者は製品を使いにくくなります。あるいは、さらに悪いことに、同じ人々が他の製品を探すしか選択肢がなくなることもあります。場合によっては、他に選択肢がないため、ユーザーは何とかして問題を解決する方法を見つけ出すしかなく、最善を尽くさなければなりません。
参照:採用キット: バックエンド開発者(TechRepublic Premium)
何かをうまく動かすプロセスで、私はいつも苦労しています。そして、これはしょっちゅう起こることです。たまたま20年以上もこの仕事に携わってきたので、質の低いドキュメントを作成することは私にとっては当たり前のことです。残念ながら、誰もがそうであるとは限りません。ユーザー、管理者、開発者がまたしてもドキュメントの劣化に遭遇すると、それに伴うフラストレーションは計り知れないものになります（特に、何かを稼働させるよう経営陣にプレッシャーをかけられている場合はなおさらです）。
これは、ユーザーがサポートを求める企業を持たないオープンソースソフトウェアにおいて特に重要な問題です。多くのオープンソースプロジェクトでは、リリースに合わせてドキュメントを整備するのに十分なボランティアを集めるのに苦労しているため、この問題はさらに顕著になっています。
劣化した文書に対して何ができるでしょうか?
まず、大規模プロジェクトではドキュメントを特に重視する必要があります。これは当然のことです。開発者にドキュメント作成を任せるのではなく（開発者は必ずしもエンドユーザーや管理者レベルでの説明が得意とは限らないため）、ドキュメント作成チームを必須として採用することを検討すべきです。確かにコストはかかりますが、機能的であるだけでなく、理解しやすいドキュメントを作成することは、ブランドロイヤルティと継続的な成長という形でその効果を測ることができます。
小規模プロジェクト（ドキュメンテーション専任チームを編成する余裕や人員を確保できない）では、ボランティアの活用が必須です。しかし、多くの小規模プロジェクトがこの点で苦労しています。効果的なドキュメント作成プロセスが確立されていないだけでなく、採用活動の時間の大半を開発者の採用に費やしているのです。こうした小規模プロジェクトでは、ドキュメントの一貫性、最新性、そして動作の確実性を確保するためのチーム編成を最優先に考える必要があります。ソーシャルメディアはそのような人材を見つける優れた手段ですが、時間と労力がかかります。その努力は、ドキュメントの劣化を防ぎ、ユーザーの満足度を向上させることにつながります。
それが実現するまで、ユーザー、管理者、開発者はあなたのプロジェクトを統合したり利用したりするのに苦労し続けるでしょう。そうなれば、潜在的なユーザーはプロジェクトから離れ、別のプロジェクトを探し求めるでしょう。そのような事態（そしてそれに伴う評判の低下）を許容できるでしょうか？
ドキュメントがコードと同じくらいプロジェクトにとって重要な要素になるべき時がとうに過ぎています。そうなるまでは、アップデートをリリースするたびに、ハウツー、Readme、ドキュメントのどこかに不具合が生じることを想定してください。
後回しにせず、今すぐその問題を解決しましょう。
Jack Wallen によるビジネス プロフェッショナル向けの最新のテクノロジー アドバイスをすべて知るには、YouTube でTechRepublic の How To Make Tech Work を購読してください。
