【データ基盤チーム ブログリレー 3日目】
こんにちは、エンジニアリンググループの石塚です。
趣味は筋トレです。好きなトレーニングはレッグカールです。今年2023年の1月に第一子が爆誕し、毎日子供の笑顔に癒されております。一方であまり言い訳にはしたくはないですが、事実自分自身の自由に使える時間は少なくなったなと感じております。そんな中でもトレーニングの時間は作りたいので、24時間ジムに契約して妻と娘が寝ている早朝の時間にウホウホトレーニングをしている今日この頃であります。時間のありがたみをとても感じるようになりました。
これは仕事でも同様かと思います。有限な時間の中でタスクを取捨選択して価値ある成果を上げていく事が仕事では求められます。ドキュメンテーションはその価値ある成果につながる時間を増やす一助になるかもしれません。
この記事では、ドキュメンテーションの必要性について言語化します。改めてその必要性を認識して、目的をもってドキュメンテーション作業にとりかかれる手助けになれたらと思います。
※ドキュメントの量産を推奨する記事ではありません。
※ドキュメントの内容にとらわれず、今の最適を求めていく姿勢を持つことは重要であると考えております。
※この記事ではテクニカルライティングのtipsやドキュメントの管理/整理方法については言及しません。
ドキュメントと言ってもとても多岐に渡りますが、この記事では以下のものをイメージしております。
- ソースコードドキュメント
- 手順書(開発環境構築手順書等)
- API仕様書
- 運用マニュアル
- ユーザーマニュアルやFAQ
- トラブルシューティングガイド
その他プロジェクトによってエンジニアが主担当として作成すべきドキュメントがあれば、そのドキュメントと照らし合わせて読んでいただけると幸いです。
ドキュメンテーションが時間を生み出す
コロナの流行がきっかけで生活様式が変わり、仕事ではリモートワークの実施を始めた企業が多いかと思います。対面でのコミュニケーションからテキストベースのコミュニケーションが増えた昨今では、ドキュメントがそのコミュニケーションを補助する役割として機能する場面が増えたのではないでしょうか？
ドキュメントがあるために時間を生み出し労力を節約できる等の恩恵を受けられる実際の例をあげてみます。
◯仕様書や機能概要のドキュメント化(ソースコードドキュメントや機能の仕様書等)
- 追加改修時のキャッチアップ時間の節約になります。
- そのドキュメントを議論のベースにして、今の最適な仕様を再検討することに繋げられます。
◯手順書のドキュメント化(開発環境構築手順書、運用マニュアル)
- 新人のオンボーディングの補助になり、スケールしやすい組織が作れます。
- 運用手順がまとまっていることで持続可能なサービスの保守が可能になります。
◯トラブルシューティングガイドのドキュメント化
- 同様のトラブルや問い合わせが来た時の対応工数の削減になります。
◯ユーザーガイドやFAQのドキュメント化
- 充実しているユーザーガイドがあると、そもそもの問い合わせの頻度を減らせる可能性があります。
- 利用者全員がユーザーガイドやFAQを見るわけではないですが、事前に作成することで問い合わせ対応もリンクを参照させるだけの対応で時間の削減につながります。
属人化の解消
ドキュメントが整っていることで副次的に得られる恩恵の1つに作業や開発の属人化を解消できることがあります。作業やプロダクトの機能に詳しい人が属人化していると短期的には効率良くタスクを完了できることでしょう。ただし、長期的に見ると次に挙げるような不利益があります。
- 機能変更時の判断も属人的になる。相談できるメンバーがいないため最適ではない偏った判断で進めてしまう可能性がある。(プロダクトへの不利益)
- 属人化案件を持ったメンバーの私的な事情(家庭の事情、病欠、退職、育休等)でチームメンバーが疲弊する可能性がある。(チームメンバーへの不利益)
- 2の状況は属人化タスクを持っているメンバーに私的な事情での休暇を控えさせてしまう可能性がある。(属人化作業を持っている人自身への不利益)
これらの不利益が出る前にドキュメント化ができるよう、その重要性をチーム内の共通認識として形成できるとハッピーになれるかもしれません。
ドキュメンテーションを推進する文化をつくる
なかなか浸透しづらいドキュメンテーション作業を推進するためのtipsを4点紹介します。
1. ドキュメント作成した人に対して感謝の気持ちを伝える
ドキュメントを作成してくれた人やソース内に有益なコメントを残してくれた人に積極的に感謝の気持ちを伝えましょう。
書き手にとってはドキュメンテーションの恩恵やインセンティブを感じることが少ないというのもドキュメントテーションを遠ざける理由の1つであるかもしれません。また、読み手がドキュメンテーションの恩恵を受けるタイミングは書き手の作成直後からは時間差があって訪れることが大半かと思います。
感謝の気持ちやフィードバックを言葉やリアクションで伝えることでその時間差を埋めることができ、書き手の今後のモチベーションにつながっていくことも期待できます。
2. ドキュメントをコードのように扱う
ソース管理配下にドキュメントを置くことで、コードと同等のワークフローを経ることになり、コードと同様に保守されるドキュメントを作成することが可能になります。 これはGoogleのソフトウェアエンジニアリングの書籍でも推奨されていた内容になります。
README.mdがイメージしやすい例かと思います。他にもソースコード内のコメントもドキュメンテーションの1つと認識してレビュー対象として保守していくことをおすすめします。
3. プルリクテンプレートのチェック項目をつくる
「ドキュメントの整備はできているか？」のようなチェック項目をプルリクテンプレートで用意してみるのもおすすめです。
2の内容との違いは、ソース管理配下とは切り離れてドキュメントを必要とする時の気づきになるということです。
4. ドキュメンテーション自体をタスク化する
開発タスクと同列のようにドキュメンテーションもタスク管理するのもおすすめです。 実際に期日を設けてタスクを管理し、朝会やスプリントプランニング等の共有の場があればそこで「やります！」宣言をしていくのも良いかもしれません。作成するドキュメントが本当に必要なものかを共有の場で議論できるのも無益なドキュメントの量産を防ぐためにはおすすめです。
一方で、新規サービスを立ち上げる際はスピード感をもってプロダクト開発に専念するため、ドキュメンテーションにかける時間が惜しいこともあるかもしれません。 そんなときにもドキュメンテーションをタスク化しておき、忘れないためにバックログに積んでいくのも1つの手かと思います。
散らばるドキュメント、あなたは何処へ？
サービスやプロダクトがスケールしていくと、コードと同様にドキュメントの量も肥大していきます。適切に階層化された場所にドキュメントが配置されてアクセシビリティが高い状態になるのが理想ですが、現実はそうでないかもしれません。
社内で利用するツールもその時最適なツールを選定している歴史的経緯もあり、古い社内Wikiと新しい社内Wikiがあったりします。また、チームや事業部ごとに主として利用しているツールも異なることもあります。
このように散らばっているドキュメント探しで消耗してしまうのは辛いものです。少しでもその負荷を減らせるための方法としてChromeのサイト内検索のショートカット設定をおすすめします。
サイト内検索のショートカットのおすすめ
サイト内検索とは文字通りサイト内にある検索機能のことです。 Google Driveを例にすると↓の画像の赤枠の部分で、ドライブ内の資料を検索。
この検索をショートカットに設定することで検索負荷を減らせます。
簡単に設定方法を紹介します。(※Chrome version 114での設定方法になります。)
- 設定 > 検索エンジン > 検索エンジンとサイト内検索を管理する
- サイト内検索から追加ボタンを押下する
| 設定項目 | 説明 |
|---|---|
| 検索エンジン | 検索対象の任意のサービス名 |
| ショートカット | 自分が覚えやすいショートカットを入力。ex) Google Driveならgdとか、GitHubならghとか |
| URL | 検索エンジンでサイト内検索をした時のURLを参照し、検索文字列を%sで置き換えた値 |
URL設定についてはGoogle Driveを例に説明します。
Google Drive内でhogeと検索すると、URL上はhttps://drive.google.com/drive/search?q=hogeとなります。hoge部分が検索句としての変数になるのでこれを%sで置き換えたhttps://drive.google.com/drive/search?q=%sをURLに入力します。
これで設定は完了です。
実際に利用するときは、Chromeのサイト内検索に設定したショートカット + スペース + 検索文字列 + enterで検索。
エンジニアに限らずですが、ついついタブで開くを多用してカオスなことになってないでしょうか？
この状態で検索したいサイトを探したり、ブックマークから該当サイトを開いて検索窓を探して...というのは正直手間がかかります。
下記の手順でショートカットを利用して検索することで大分負担軽減になっており、とてもおすすめです。
command + Tで新しいタブを開く(この時Chromeの検索窓にカーソルが当たっている状態)- サイト内検索のショートカットを利用して検索したいサイト内を検索する
ここではGoogle Driveを例にしましたが、利用している社内WikiやGmail、GitLab等サイト内検索が存在するサイトの検索ショートカット設定を積極的に追加して検索負荷を軽減することをおすすめします。
まとめ
以上、ドキュメンテーションが時間を生み出す事例と共に、ドキュメント作成の推進とドキュメントの辿り方のtipsを紹介させていただきました。今一度ドキュメンテーションから受ける恩恵を認識してそれに向き合っていただくきっかけとなれば幸いです。
We are Hiring!!
エムスリーではエンジニアを募集中です。
私自身フリーランスとして参画させていただいているのですが、その肩書きを意識することなく裁量をもって働く事ができる会社です。フリーランスで参画を検討している方にもとてもおすすめです。
少しでもご興味を持った方は、以下ページよりカジュアル面談等に申し込み頂ければと思います！
