エンジニアのためのドキュメントライティング読みました。 最近の仕事の悩みに対して、方向性を示してくれた良い本でした。
自分のチーム内にドキュメントの文化が無い人にお勧めします。 全体のざっくりした感想だと、この手の本にありがちな小言っぽいことは書いてなく、作って意味のあるドキュメントはどうあるべきかを書いてあります。仕事のドキュメントで悩んでいる人には、具体的な取り組みのアイデアがいっぱい見つかるでしょう。
背景
うちの会社は転職者が多く、開発への考え方がバラバラ。当然、ドキュメントに対する考え方もバラバラで必要なドキュメントがなかなか揃わない。今の仕事は各部署からの寄せ集めチームでもあり、ドキュメントのテンプレートみたいなものもない。
世代間の格差も結構ある。ベテラン勢はドキュメントは印刷され保管される前提であり、表示にバージョン、日付、部署、作成者などを明記するべきだと思ってる。ドキュメントの承認印的な物が欲しい人もいる。一方若い人はドキュメントはVCSに組み込まれる物であって、作成日や作成者の情報はVCSで持っておけば良いという考え方があり、ドキュメントに作成者などを書かない。
若手の言い分もわかるけど、社外に出て行く文章はバージョン管理いるでしょう・・・みたいな悩みを抱えていたところ、この本を見つけました。この前に、Googleのソフトウェアエンジニアリングを読んで、ドキュメントについて考えることがあったけど、googleの本に書いてある事は大概の会社には当てはまらない。Googleのようにドキュメントの作成や管理をスケールさせる意味はまずない。
そんな感じでもやもやしているところでこの本を買って読むことにしました。
良いところ
ドキュメントの作り方みたいな本は、結構小難しいことがかいてあります。ドキュメントには承認プロセスが必要とかなんやらかんやら、用語の定義はこうしろ、フォントはこう使い分けようなんやらかんやら。こういうのは大企業のドキュメント管理を専用にする部署向けであったり正しいドキュメントを書くためのルールだったりします。エンジニアの気持ちやそれが何の役に立つのという観点はあまり考慮されないパターンが多いです。そもそもドキュメントを書きたくないという気持ちから目を背けてます。
この本はスタートアップの会社がWebサービスを公開するというシチュエーションでドキュメントの書き方と運用について書かれています。アメリカの本にありがちな謎の寸劇っぽい部分がすごく短く読みやすいです。堅い本に比べると、なぜ正確なドキュメントが必要なのかという点は説明少なめです。まあ、この本を読んでいる時点で何かしらの課題を持っているはずなので、ドキュメントの重要性をくどくどと書いてないのは良い。
書く側の気の持ちよう的な所が書いてあって、レビューする側、される側の心構えも書いてありました。作成したドキュメントがどれだけ役に立ったかの計測についても結構な量があり、お堅い本にはでてこないトピックで勉強になりました。
とにかく「ドキュメントを書く」事を目的とせず「ドキュメントを運用する」事にフォーカスされています。
関心した所
ドキュメントを書くに当たって
ドキュメントは開発していく物。コードと同じ。 大事なのは一貫性。用語、見出し等、一貫性があると読みやすい。 ドキュメントは流し読みしやすいように書く。 一回で良い物を作ろうとしない、文章で悩むくらいならレビューしてもらって他人に指摘してもらった方が早い。
手順書
一度開発者が正確に書いてから、ユーザー目線で改善していく。このやり方を作成者も意識していると、頑張って書いた手順書に対してわかりにくいという指摘も受け入れやすい。ユーザーの立場で正確に手順を書くというのはできないので正確に書くのは開発者、その後分かりやすい手順書にするのはユーザーの立場の人という分担は直ぐにでもチームに投入したい。
API
APIのドキュメントは大事だ。この本はWebサービス前提だが、何か開発した物に対して使い方がわかるドキュメントが大事なことはWebサービスに限らない。
APIのドキュメントを書くための専用のトレーニングコースまである。 https://idratherbewriting.com/learnapidoc/
サンプルコード
サンプルコードは、説明したいこと（もしくは動かしたいこと）に特化する。小粋なアルゴリズムは不要。 クラス名や変数名は、your_password等普段使わない説明的な名前をつかってもOK。
まとめ
本の章立てはドキュメントを作るところが前半、後半は運用について書かれています。 今、自分のプロジェクトでドキュメントについて悩みがあるなら、該当する箇所、もしくは今後ぶつかるであろう課題について書いてあります。
ドキュメントもチームの文化なので、良いチーム文化を作るためにも、みんなで納得しながらドキュメント作りたいですね。
