最終更新日: 2024年02月27日(月)
1. ご挨拶
初投稿となります。
ToB 高校向けスタディサプリの開発エンジニアをしている @hayat01sh1da です。
私のチームでは先生方が生徒さんに向けて配信するアンケートや志望校調査など、進路選択という学事に関わる機能の開発を行なっています。
当社は部活動が盛んで、私自身は卓球部・カラオケ部・山岳部(非正規部員)に所属しています。
趣味はカラオケ・旅行・サウナ・お酒です。
今年は長めの冬季休暇を頂き、ニュージーランド(Queenstown → Mount Cook → Lake Tekapo → Christchurch) を旅行して来ます。
大学 4 年次を休学してオーストラリアで 1 年間ワーキングホリデーをしていた時に Queenstown を旅行した以来なので、とても楽しみです！
宝物は実家にいる御年 21 歳の愛猫です(写真は 2014 年当時)。
2. 本記事執筆のモチベーション
私が所属する部署ではテーマフリーの LT 会や技術トーク会の定期的な開催があり、そこで時々発表をしています。
これまでは大学時代の専門であった言語学(英語・日本語)を主なテーマとしていましたが、今回は社内ドキュメンテーションという実用的なテーマを取り上げました。
昨年、とある年次メンテナンスプロジェクトのメイン作業者にアサインされた際、文書が散在しており情報の参照や知見の獲得にとても骨を折ったことが原体験です。
次の年の担当者には同じ思いはして欲しくないと思い、苦労の末必要な情報を集約・体系化して決定版となる Handbook を作成しました。
その経験で得た知見を共有しようと考えましたが、私個人の経験論だけで物事を語るのは良くないと考え、以下のステップを踏むことにしました。
- 「ソフトウェアエンジニアにとってのドキュメンテーションとは？」の理論をインプットする。
- 理論を実践するにおいて遭遇するトレードオフを踏まえ、実用的な再現可能な手順を洗い出す。
- 「一般論編」「実践編」の 2 パートに分け、前者は非エンジニアも対象の LT 会で、後者はエンジニアだけが参加する技術トーク会で発表・議論する。
その過程で作成したのが以下のスライドです。
※ スマホ・タブレットでご覧の方は初期表示が正しくされないことがありますが、スライド下部のハイパーリンクを押下して別タブを開き、閉じて本記事に戻ってくると正しく表示されるようになります。
英語版はこちら
日本語はこちら
この記事では、特に「実践編」の発表を通じて私が学んだことを共有したいと思います。
3. ワークショップを通じて得たフィードバック
技術トーク会では「実践編」の発表を行うだけでなく、そこでエンジニアに簡単なワークショップを行ってもらいました。
- 個人またはチームがドキュメンテーションにおいて抱えている問題を 'Pains' に列挙する。
- 1 を解決するための取り込みや効果的な解決策があれば 'Approaches/Solutions' に列挙する。
- その他、参照性・変更容易性・効率を担保するためなどの雑多な秘訣があれば 'Tips' に列挙する。
3-1. Pains -過去抱えた/現在進行形で抱えている辛み-
エンジニアが抱えている Pains を要約すると、以下の 3 つに集約出来ます。
- 集約・体系化されていないことに起因する情報検索コストの上昇
- 執筆作業コストや管理・編集コストに起因する文書の陳腐化
- 口頭や Slack で雑に伝えてしまっているが、幸か不幸かそれで完結出来るのでドキュメンテーションの必要性を感じないという現実
エンジニアにブレストしてもらった以下の内容は、きっとどの開発組織も共通して抱えているものではないでしょうか。
私自身ヘビーなドキュメンテーションを行った中で感じたことはきっと共感されないと思っていましたが、意外にも同じ Pains を抱える仲間が多くいて安心しました(←するな)。
| Category | Pains | コメント |
|---|---|---|
| 情報検索 | ドキュメントが散逸していて探せない、集約された各場所がない | 集約・体系化を見越さず「とりあえず」書いたドキュメントが散在すると陥る状況ですね。 |
| ドキュメントが散在しており探すのが難しい | ||
| 情報の検索が職人技 | ドキュメントの管理を適切に行わないと欲しい情報がスムーズに手に入らないことが往々にしてあります。 | |
| 書いても存在を思い出せない | 集約・体系的でない断片的なドキュメントは時間の経過とともに(物理・記憶ともに)埋もれていきますので、必要なものはブックマークしておくのが良いですね。ブックマークも多くなると散らかってくるので、定期的に整理・断捨離しましょう。 | |
| 文書の陳腐化 | 更新すべきドキュメントはあるが、どれを更新すべきか把握しきれない | 集約されていない断片的な複数のドキュメントが存在するので、どれをアップデートすべきか分からないということですかね。 |
| どれが最新のドキュメントかが分かりづらい | 集約されていない断片的な複数のドキュメントが存在する場合に発生するので、ある時点で決定版を作成するのが良いですね。 | |
| ストック情報なのかフロー情報なのかの区別が曖昧 | ストック情報とは後から何度も見返すことが多い情報のことで、フロー情報とはメールやチャットでやりとりされる一時的な情報のことです。フロー情報の中の重要な情報をストック情報化されていないと起こり得る現象ですので、こまめに清書する習慣が大切ですね。 | |
| ドキュメントが古い | Ownership が不在もしくは不明確で、誰もドキュメントの品質保持責任を持っていないと陥る現象ですね。ドキュメンテーションに取り組む最初期にきちんと握り合っておくことが大切ですね。 | |
| ドキュメントが更新されない（ドキュメントがあることを知らない） | Ownership が不在もしくは不明確、もしくは適切に引き継がれていないことが原因かと思われるので、成果物は然るべきステークホルダーに惜しみなく広報すると良いでしょう。 | |
| 作業コスト | ドキュメントを書くのが退屈 | 得手・不得手や向き・不向きがありますが、作業が長期化すると退屈度が増すので、短期決戦で済むような分業体制やワークフロー設計などの工夫をすると良いでしょう。 |
| プロダクトが絡む仕様などは devs だけでなく TPM とも連携しなくてはならず、ドキュメンテーションコストが一気に跳ね上がる | これはドキュメンテーションに限らず技術者だけで完結する業務は多くはないので、非技術者にも理解出来る言語化能力は必須スキルですね。 | |
| ドキュメント化されていない知識がある | 口頭伝承で完結するのは短期的には楽ですが、中長期的には知見が形に残らないのでこまめに明文化すべきですね。一気にドキュメンテーションをすると作業コストがとても高くなります。 | |
| 仕様が複雑過ぎてドキュメントに起こすための調査コストが高すぎると感じる | 未知のドメイン知見を明文化する場合に発生するケースですね。作業コストが高くつくのは確かに辛みです。一方でその中で知見を獲得し、明文化することで知識に血が通う嬉しみもあるので悪いことばかりではないと思います。 | |
| どこにどんな性質(動的・静的)の情報があるか把握するのに慣れるまで時間がかかる | 理論(基本的なドメイン知見)をインプットとした上で、それだけ実践(実装・テスト)の経験を積んで理解を深められるかによると思います。ある意味でこれは時間が解決するところでしょう。 | |
| ドキュメント業もコードと同じでスキルがいる | 確かに一定の言語化スキルは必要で一朝一夕には身に付かないものです。しかし、特殊能力を要求される訳ではないので、普段の明文化習慣の積み重ねで「当たり前」を鍛えるしかないと思います。 | |
| 管理・編集コスト | 二重管理を避けるために英語で書いても読んでもらえないがち | 当部署 SRE チームは国内と海外のインフラを管理しているという特殊な背景に起因する事情です。日本語と英語それぞれでドキュメンテーションをすると、両方を同期的に最新化しなければならず管理コストが嵩んでしまいます。それを避けるため英語文書に一本化しているのですが、英語が得意ではないエンジニアには敬遠されてしまうという辛みを抱えています。このトレードオフはどのように解消すべきなのか、現時点で私にも解決策が思い浮かんでいません。 |
| その内容の記述に至った背景 (合意や議論など) が不明で、変えていいのか分からないことがある | 古の議論やソースコードを紐解く考古学をしなければ対象の情報を更新して良いかの判断が付かないことがあります。当事者が既に退職済みである場合はもはや打ち手はなくなるので、少なくとも私たちは後学のためにきちんと記録や知見を明文化して残しておく責任を果たしていきましょう。 | |
| その他 | 「いつもの」みたいな情報(PWなど)って関係者は結局全員把握しているので、ドキュメントに書いてしまってはだめか、または秘匿情報をまとめるドキュメントがあるべきとか？ | ※ 誤解を避けるため念の為補足しますが、ここでの PW は開発ユーザのパスワード等を指しており、本番環境については適切に管理を行なっています。 |
| 読者への告知 | 書いた文書を通してステークホルダーに知見をインプットしてもらうのが目的で、読んでもらわないことには何も始まりません。出来上がった成果物は惜しみなくその存在をアピールすると良いですね。 | |
| 雑に Slack のリンクを貼って終わらせがち(反省はしている) | 共有される側は辛いです。最新の情報と背景をシンプルに知りたいのに、それに至るまでの侃侃諤諤とした議論はノイズとなりがちなので、フロー情報の中の重要な情報は適切にストック情報化しておくと良いですね。 | |
| 口伝で伝わっている物事が結構ある | コストを短期的な視点ではなく中長期的な視点で捉えると行動が変わってくると思います。 | |
| snippets-ja (スニペットではない) | 重要な情報が snippets-ja という雑情報置き場に書かれていることがあります。重要な情報は然るべきタイミングで集約・体系化して決定版ドキュメントを起こすと良いですね。 |
3-2. Approaches/Solutions -Pains を解消するために取った方策や導き出した解決策-
エンジニアが抱えている Approaches/Solutions は残念ながら文書の管理に関する 2 つしか挙がりませんでしたが、とても大事な意見なので深掘りしたいと思います。
3-2-1. えいやで場所を決め打ちしてしまう(e.g., GitHub Wiki + Google docs しか使わない)
ドキュメンテーションにおいてまず一番最初に直面することが多いのは「どこに書こう？」という問題です。
参照/編集のしやすさやリッチな描画などを求めて公開場所を延々と探求すると、いつまで経っても知見を明文化する時がやって来ません。
まずはどこかに知見をアウトプットして具象化(見える化)することが大切で、そのためには公開場所を決め打ちしてしまうのが良いです。
その公開場所では都合が悪くなったら、その時により適当な公開場所を検討すれば良いのです。
まずは文書化して、集約・体系化したい情報を明文化することが大切です。
3-2-2. 個人的に、2023/12/05時点で〜みたいな書き方を心がけている
文書化された情報はある時点のスナップショットに過ぎず、放置するとあっという間に情報は古くなって陳腐化してしまいます。
更新日時が明記されていないと、その情報が最新なのか古いのかの見分けが第三者には付きません。
古い情報を鵜呑みにしてしまうと、正確な情報と乖離が生じて害になりかねません。
一方、第三者が参照することを前提に「2023/12/05時点」というタイムスタンプを明記しておくと、第三者は最新情報との差分がある可能性を意識しながら読むことが出来ます。
また、タイムスタンプがあまりに古いものは情報探索対象から外せるので、ノイズを最小限に抑えることが出来ます。
どの時点のスナップショットなのかを明記することは読み手に対する思いやりである、と言えます。
3-3. Tips -効果的な手法-
| Category | Tips | コメント |
|---|---|---|
| ツールの活用 | ChatGPT に聞く | 文明の利器の活用はドキュメンテーションにおいても必須スキルかも知れないですね。 |
| 使用するツール制限するが無理に一つに定めない | 選択肢がありすぎて逆に選べない状態を回避するため縛りは設けますが、それはあくまで手段であり目的ではないので柔軟に対応するということですね。 | |
| ブラウザの検索エンジンに GitHub を追加する | 情報検索対象に GitHub も含めることで最新の仕様や要件を色濃く反映したコードから情報を読み取るという意図ですかね。 | |
| 文書の管理 | コードと同じリポジトリで管理する。 | 同一のリポジトリであれば、コードと文書の更新はワンセットとなるので陳腐化を防ぐのに有効そうですね。 |
| 最終更新日を必ず付ける | 「 3-2-2. 個人的に20231205時点でみたいな書き方を心がけている 」と同一の内容ですね。 | |
| GitHub で管理する。Pull Request 便利。 | 差分が分かりますし、suggestion 機能はレビュー時にとても便利ですね。 | |
| 文書化の準備 | ソースコードを読む | 最新の仕様や要件を色濃く反映したコードから情報を読み取るという意図ですかね。 |
| 英語を勉強する | 英語でドキュメンテーションをすることが要求される場合は必須スキルですね。 | |
| 執筆方法 | 真面目に文章で書かない、箇条書きを使う | 文章にすると文と文の論理展開を気にしなければなりませんが、箇条書きにすることでそれを気にせず書けるので知見のアウトプットが容易になりますね。 |
| 一つの Google Docs に書き連ねていく | これはトレードオフが存在していて、情報が集約化されるメリットがある一方で、重厚長大になると検索性が悪くなるデメリットもありますね。 | |
| 長大なドキュメントは Google Docs でレビューを受けてから GitHub Issue に転記する（GitHub Issue だとレビューしづらい） | どのツールを使うかはケースバイケースですが、情報の正確性を担保するにはレビューしやすい環境が必要であるということですね。 |
4. オーディエンスからの反響
「ワークショップ」を行った日とは別日に行いましたが、その日は参加者が少なかったため少数のフィードバックしかもらうことが出来ませんでした。
しかし、その少ないフィードバックはどれも重要な意見だったので漏れなく共有させて頂きます。
4-1. 気づきや学び・NEXT ACTIONS
私自身の NEXT ACTIONS は以下の 2 つです。
- aya-issue の Wiki ページを年明けのリハビリ期間に全部整理する
- StudySapuri Product Team Blog に今回の発表内容を記事としてエントリーしよう
- この記事のことです
また、別のエンジニアは以下の気づきと学びを書き出してくれました。
- 「読み手に知見をインプットしてもらうことが前提なので、書いたらちゃんと広報する」という点について、個人的にもっとできる部分があるなと感じました
- 書いた文書を通してステークホルダーに知見をインプットしてもらうのが目的であり、読んでもらわないことには始まりませんので、出来上がった成果物は惜しみなくその存在をアピールすべきだと考えます
- 入社したころは未来の自分の記憶を信用しまくっており忘れたりしていたので、「信用しない」という共通点にはとても共感しました
- 人間は忘れる生き物なので、それを見越して情報を整理して残しておく必要があります。
4-2. プレゼンター(@hayat01sh1da)へのフィードバック
スライドの構想〜執筆まで 2 ヶ月ほど費やして「社内ドキュメンテーションとは？」のテーマに本気で向き合った甲斐がありました。
とても嬉しいコメントです。
弊部署の各チームの文化として根付くような活動に繋げられると組織全体でより良くなると思いますが、まずは私の所属するチームにしっかりと根付かせて成果を出す足元を固めるという草の根活動から着実に進めて行きたいと思います。
いい話だった。ドキュメンテーションのわかり手として、横断的に展開していって欲しいと思った
4-3. Slack での反応
Slack 上の実況中継では以下のような感想が流れていたので、キャプチャでご紹介します。
5. おわりに
構想〜執筆と、学生時代〜社会人までのドキュメンテーションスキルの磨き込みや経験の積み重ねに相当の時間を費やし、万全の準備をして発表に臨みました。
ただ、その分重厚長大な内容になってしまい、ご清聴頂いたエンジニアには負担をかけて申し訳ない気持ちになりました。
この記事を読んで下さっている読者の方も同じ感覚をお持ちになるかも知れません。
ですが、それだけの思いがあるのだと受け取って頂けると幸いです。
ドキュメンテーションはその難易度と重要度の割に過小評価されている業務であり、そのスキルも単体では高く買われることは多くありません。
しかし、サービスを作り提供する仕事に就いている以上、業務が技術者だけで完結することは少なく、技術者・非技術者の双方が理解出来る言語化能力はソフトウェアエンジニアにとってとても重要なスキルです。
この記事を通して、読者の皆さんがドキュメンテーションについて考えるきっかけやヒント、Tips を得て下さればとても嬉しく思います。
