読んだきっかけ

『ユーザーの問題解決とプロダクトの成功を導く　エンジニアのためのドキュメントライティング』という本を読んだことがきっかけで、ドキュメンテーションについてもっと詳しく知りたくなったことがきっかけです。

nda-desu.hatenablog.com

しかし、ドキュメンテーションを扱った技術書は、ほとんどないわけです。

そんな中、積読していたGoogleのソフトウェアエンジニアリングの本に、ドキュメンテーションの章があったのを発見しました。

分厚くてなかなか手が出せていなかったこの本ですが、ドキュメンテーションへの関心が高まったことで、その章だけを読んでみることに決めました。

読んでみて

内容的には非常に良かったと感じました。

まず、Googleでさえドキュメンテーションについては管理も整備も苦労していたことが明かされており、改めてドキュメンテーションの難しさを痛感しました。一時期は、Googleの開発者の不満点の第一位が、「ドキュメンテーションの品質」だったそうな。。

具体的なよかった点については、後述しますが、哲学と具体策がバランスよく明確に書かれていたのが、すごくよかったです。

ドキュメントとは何か、どのような考え方で向き合っていけば良いのかという姿勢や哲学的な話から始まり、具体的にどのような観点でドキュメントを作成するとよいか、管理はどうするのかなど、具体的なところまで詳細に記されていて、非常に参考になりました。

学びになったポイント

では、ここからは学びになったポイントについてあげていきます

1. ドキュメンテーションが「つまらない」とされているのは、なぜか？
2. ドキュメンテーションはコードのようなものである
3. 効果的なドキュメントを作成する際に考慮すべき要素とは？
4. 優れたドキュメンテーションとは？

順にお話しさせていただきます。

ドキュメンテーションが「つまらない」とされているのは、なぜか。

まずは、ドキュメント管理や作成がなぜ進まないのかに関する解説からです。

たしかに、ドキュメントを書く作業が楽しいという話はあまり耳にしませんよね。一方で、質の高いドキュメントがプロジェクトに大きな恩恵をもたらすことには、みんな納得しています。

それなのに、どうしてドキュメンテーションが楽しくないと感じられるのでしょうか？

こんなことは、考えてみたことがなかったすね。本書では、理由について、いくつか紹介されています。

恩恵が即時的ではないから

まず、ドキュメントの恩恵が即時的ではないからです。

自動テストを書いたらすぐに結果が出て、効果が分かりますよね

しかし、ドキュメントの場合、書いた本人が直接得をするわけではありません。もちろん、他のメンバーや将来の自分には大きな助けになりますが、その恩恵は少し先のことになります。

文章を書くスキルとプログラミングスキルが別物だと考えられているから

次に、文章を書くスキルとプログラミングスキルが別物だと考えられていることが理由の一つです。

多くのエンジニアは、コードを書くのが得意でも、文章を書くのは苦手だと感じているからだと解説されています

既存コードの保守を楽にしてくれるという認識が十分にないから

さらに、ドキュメンテーションが既存コードの保守を楽にしてくれるという認識が十分にないことも、ドキュメント作成に対する意欲を削いでいると。ドキュメントの恩恵は長期的なもので即時的ではないという話が前にありましたが、労力をかけてもすぐには見返りがないというのもわかりますね、気持ちとしては。

以上、いくつか理由を書きましたが、おっしゃる通りですよね。では次にこの点を押さえた上で、次にGoogleではどのようにドキュメンテーションに取り組んだのかが紹介されていきます。

ドキュメンテーションはコードのようなものである

引用です。

単一のプログラミング言語を主要言語してプログラムを書いているソフトウェアエンジニアであっても、特定の問題を解くために別言語に手を伸ばすことも多い。(中略)ドキュメンテーションも同様であるべきだ。ドキュメンテーションとは、道具であり、特定タスクの達成のために、別の言語で書かれているものである

ドキュメンテーションをコードのようなものとして捉えるというこの考え、それがGoogleでドキュメンテーション文化の醸成の成功につながっていることを紹介しています。

この観点は、前回の書籍でも紹介されていましたね。

ドキュメンテーションをコードのようなものとして扱うとは、具体的にはどのように行うのでしょうか。

本書では、

1. ドキュメントのオーナーを決める
2. ソースコントロールシステムの管理下に置く
3. ドキュメントの鮮度や正確性をチェック

などが紹介されていました。

なるほど、コードを管理するの同じ思考法、同じ方法で管理する。

まー文化として浸透させるのには、時間と労力がかかりそうですが、この考えで捉えていくことで質の高いドキュメントが維持できそうですね。

効果的なドキュメントを作成する際に考慮すべき要素とは？

ここまでは、考え方に関する事柄多めでしたが、ここからは、書き方についてです。

本書で紹介されているのは、５Wの観点を持て、というものでした。

Who（対象読者）：誰を対象にしているのか明確にすること
What（目的）: ドキュメントの目的を特定し、その目的に沿った内容だけを含めること
Where（保管場所）: ドキュメントの配置場所を決め、読者が簡単にアクセスできるようにすること
When（作成時期）: ドキュメントの作成・更新日を記載することで、読者が情報の新旧を判断できるようにすること
Why（目的の確立）: 目的を明確にし、導入部分に書いておくこと

初めに整理をしておくことで、途中で目的に沿っているか、余計なことを書きすぎていないか、などもチェックできますし、ドキュメントを作成する前に、まずはこの視点で整理してみると、良さそうです。

また、保管場所の視点を持っておくことも大切だなと思いましたせっかく作っても、探しづらい場所に置いてしまったら、価値を発揮することができませんよね。

いい視点を学ぶことができました。