Engineering(SRE)、ソフトウェア開発、クラウドコンピューティングなどについて、吉澤が調べたり試したことを書いていくブログです。情報を書くときに、私が個人的に守っていて、チームメンバにもできるだけ守ってほしいルールの紹介記事です。このルールを実際に運用するためのコツについても、基本ルールの派生という形で紹介します。あって、フォーマットが決まったドキュメント(仕様書や手順書など)とは別に、各人がメモを自由に書いて共有できるような環境を想定しています。......何でもいいです。文書などにも適用できなくはないですが、文書を気軽に分けるのが難しい場面には、あまり向かないかと思います。ルール:「このページについて」という欄をページの先頭に用意し、そのページの概要を1〜2文で書く守ってほしいルールはこれだけです。単純ですが強力で、きちんと守ろうとすると意外と面倒なルールでもあります。何かのインストール作業をメモしておきたい場合、「このページについて」欄には以下のような文章を書きます。ソフトウェアBをインストールした際のメモです。手順(これ以降に、実際に実行した手順のメモ)または、何か新機能の実装をしたくて、事前に設計を検討した場合は、こんな感じで書きます。このページについてこれは、機能Cの設計についてチーム内で議論するために、個人的に作成した設計案です。設計の事前知識として、既存のソースコードを調査した結果も含めています。記事は、よく「〜とは、...である。」という一文から始まりますが、それをイメージしてもらえると分かりやすいかもしれません。ための情報を与えることです。実際に使っている人なら、このページにはこんなことが書いてあるだろうなーと思って読み始めたら、実際は全然違うことが書かれていた、という経験が何度もあると思います。インストール手順書かと思って読んでいたら、インストール時に試したことを適当な順序で書いてあるだけのメモだった。書いてある手順を上から順に実行したところ、途中で失敗してしまった。メモにも「このコマンドは失敗した」とか書いてある。ある機能の設計に関するメモかと思ったら、単なる設計案の一つだった。最終的に実装されたソースコードの設計とは全く一致していなかった。書かないで欲しい、とか、そういう中途半端なメモは消して欲しい、とか言いたいわけではありません。読まなくなるという悪循環を起こしかねません。有効な情報を書いていっても、その情報は読まれない、というもったいないことになってしまいます。判断することも十分ありえますし、結果として必要な情報が書いてなくても、期待を大きく裏切ることにはなりません。全体でそういう状態を保ち、モラルハザードを防ぐ......というのがこのルールの目的です。以下は、このルールを実際に運用するために守ったほうがよい、このルールの派生系です。派生(1):ページを更新し終わったタイミングで「このページについて」の内容を見直すページの内容を色々書いているうちに、最初に書こうと思っていた内容とはズレていってしまう、ということはよくあると思います。理想的には、内容がズレた時点で直したほうがよいのですが、少なくともページを更新し終わったタイミングでは必ず直すようにしましょう。設計案を色々書いていたつもりが、最終的な設計についてもそのページに書いてしまい、他のページにはそこまで詳しい情報がまだ書かれてない、という状態になったとします。最終的な設計のページをきちんと用意したほうが良いですが、「このページについて」欄を以下のように直すだけでも、後から読む人にとっては役立ちます。このページについてこれは、機能Cの設計についてチーム内で議論するために、個人的に作成した設計案です。最終的に採用したのは案3で、このページに書いてある案3の詳細は、最終的な設計と同じです。派生(2):「このページについて」から外れる内容が増えてきたら、別のページに分ける書いているうちに「このページについて」には書いてない内容が増えてきた、あるいは内容に合わせて「このページについて」を直したら1〜2行では収まらなくなった、という場合にはページを分けましょう。このページについてこれは、システムAの開発環境を構築するための手順書です。このシステムのサブシステムB、C、Dの知識がないと、この手順は意味不明に見えるかもしれません。そのため、このシステムのサブシステムB、C、Dの関係についても、構築手順書の途中で説明します。ようになったら、恐らくそのサブシステムB、C、Dの解説は別のページに分けたほうがいいでしょう。以下のようにリンクを書くだけにするのが無難です。このページについてこれは、システムAの開発環境を構築するための手順書です。これらの手順が何をしているか理解するためには、このシステムAの構成に関する知識が必要です。しないと、読み手が、1個の長いページのなかで、自分の知りたい情報を探しまわる羽目になってしまいます。別のページに分けたら読まれないかも?と思うかもしれませんが、そういう人は、同じページ内に書いてあってもどうせ読みません。それなら、読む気のある人向けに、少しでもわかりやすくしたほうが良いです。派生(3):他の人が書いた「このページについて」も直していい他の人が書いたページでも、「このページについて」に書かれた内容と、本文が違っていたら、積極的に直しましょう。そもそも「このページについて」欄が無かったら追加しましょう。全体の利用価値向上、モラルハザード防止です。そのためには、内容は直さずに、「このページについて」欄を直すだけでも十分意味があります。あるページを読んで、その内容が間違っていた場合、私だったらこういう文章をページの冒頭に書いて、内容は修正も削除もせずに残しておきます。調べた範囲では、このページに書かれた設計は、現在の実装と違っているようです。そのため、設計情報としては参考にしないことを推奨します。当時の設計思想など、何かの参考になる可能性を否定しきれないため、削除せずに残しておきます。書くのが一人か二人だけ、になってしまうのも困ります。そのため、「このページについて」欄以外のルールはあまり多くしないほうが良いでしょう。一般的な話として、「他人のために細かく書いてあげている」というつもりで書いていると、読んでもらえなかったときの心理的ダメージが大きいです。そのため、手間のかかる本文の品質は、自分が後で読んで困らない程度にしておくことをお勧めします。まとめ今回は、普段はあまり書かないタイプの、仕事のノウハウについての記事でした。私は自他共に認めるメモ魔で、やたらあちこちにメモを書き散らしています。やって書き溜めているメモがたまに同僚から「役立った」と言ってもらえることもあるのですが、それと同時に「自分はそこまでできないし、やらない」という反応をされることが多かったりします。書く分量が少なくても、少しの工夫で、後から読んで役立つような文章を書くことはできるはずなんだけどなあ......と思い、自分なりに本質的と考える部分をまとめてみました。普及してだいぶ経つので、今更感のある話題ではありますが、他の人のノウハウも色々伺ってみたいところです。はてなブログProMuziとも呼ばれる人。いまはBacklogのSREやってます。(1)注目記事リンク無印吉澤(旧)はてなブログをはじめよう!muziyoshizさんは、はてなブログを使っています。ブログを報告するスターをつけました引用をストックしましたストック一覧を見る閉じる引用するにはまずログインしてくださいログイン閉じる引用をストックできませんでした。再度お試しください閉じる限定公開記事のため引用できません。