この記事におけるドキュメントとは
CLOMOのサーバーサイドを担当しているMisaki-i3です。
入社してから10ヶ月が経過し、業務を通じて製品に貢献できている自覚も得られるようになってきました。
さまざまな課題に取り組む中、あらゆる場面でその重要性を感じさせたのが、調べたことや理解したことをドキュメントに出力しておくことです。
システム開発におけるドキュメントといえば、マニュアル・仕様書・設計書・報告書等を指すようですが、この記事では、調査記録・開発メモ・学習ノート等を含む文書全般のことを指します。逆に、仕様書や設計書作成には触れません。
弊社のドキュメント管理はAtlassianのConfluenceで行っています。
多くの類似サービスと同様、容易に文書の装飾や図表の挿入ができ、ページを増やしても紙は減らず、ページを削除してもゴミが出ません。
アカウントごとにパーソナルスペースがあるため、いくつページを作っても共有スペースを乱しませんし、1−2行だけ書いたきり使わなかった、メモ帳として利用したあと削除したなどという行為も気兼ねなくできます。
このハードルの低さも前提におき、私の経験に基づいた、作業の効率化に寄与するドキュメント作成についていくつか紹介します。
頭の中のメモリを開放する - 開発効率を上げる
コードを読み解く作業などでは、脳の一時記憶領域を大量に使います。
ロジックの理解に苦戦しながら、そもそもなんのために調査をしているのか、何を見つけたくて処理を追っているのかといった目的も忘れられません。コードを読む途中で新たな仮説が立てば、次に調べるべきものとして記憶に留めておくことになります。
これらの一時記憶のうち、必要になったら思い出せばよいものはすべてドキュメントに書き出してしまいます。
空いた領域はロジックの理解につぎ込み、調査に対する集中を確保する目的です。
もう少しでAが終わるから、次はBを検証しようかな。ところがAの調査中に有力な情報や手がかりが見つかり、少し脱線した隙にBのことを忘れてしまった。
このようなケースは頻繁にあります。(ありませんか? すごい)
「何か忘れている気がするなあ」ともやもやしながら別の作業に着手し、あるときBに関連するコードを見て思い出すことになるのでしょう。
問題は、そのような経験を何度も繰り返すと、何も忘れていない場合も「どうせ何か忘れているのだろうから思い出さなきゃなあ」と考えてしまうようになります。(私はなるのです)
常にもやもやし続け、思い出すことは不可能なため長く継続します。
このもやもやにメモリを食われるのは非常にもったいないことです。
これを解決する術はもちろん、次にやること、次に検証したい仮説も、思いついた時点でドキュメントに書き留めておくことです。
書き留める作業が大きな負担に感じてしまう場合を除き、「頭の片隅に残しておく」という大きな負担は避けるに限ります。
質問しようと思ったとき、質問はすでに終わっているのだ - 質問の質を上げる
新人エンジニア 質問、と検索すると、様々な質問の失敗例を見つけられます。
それら失敗の原因の多くは、「情報が整理できていないため」のようです。
「ここでエラーが出てしまったんです……
AAAを確かめようと思ってBBBを見たら
多分CCCあたりにDDDがあって……
あ、あったのはDDDじゃなくてEEEでした。
あ、そっか、BBBを見たのはAAAのついでにFFFを確かめようとしたときでした。
あ、FFFのときってことは、
あっ、勘違いでした、大丈夫です……」
良い質問をするためには、自分の持つ情報を整理し、俯瞰し、取捨選択して提供する能力が必要になります。
質問経験の乏しい初心者が情報の取捨選択を行うのは難しいものの、情報を整理し俯瞰することは比較的取り組みやすいと思います。
そのために、作業中に取ったアクション・得られた情報は、リアルタイムにドキュメント上に出力しておきましょう。
何を知りたくて、何を期待して、何を試し、何が分かったか・何が期待はずれだったかを記録しておきます。
質問をする際にはそこから選び取ります。
調査中のメモをどれだけ詳細に書くかはまちまちで構わないと考えていますが、最低限、質問や途中報告のときに使うかもしれない情報は記録しておきます。
丁寧にまとめあげる必要はありません。必要に迫られたとき整理する程度で良いと考えます。
自分に向けての報告書を持っておく - 報告のハードルを下げる
弊社では、システムの解決すべき課題は扱いやすい大きさに分割され、AtlassianのJiraというサービス上でチケットとして管理されています。
本項では、チケット管理されているうちの一件を指して「課題」と呼びます。
さて、私が課題に着手するほとんどの場合、「調査資料」として一つのドキュメントを課題に紐付けます。
前項までに紹介した作業中の記録とは異なり、調査資料としてのドキュメントは報告書のような形式で記述します。
(いまのところチームとして運用を定義しているわけではないため、内容は柔軟に変更します)
入社当初は手探りで作成していた調査資料も、半年後には形式が定まってきました。
- 主なリンク集(課題・関連ドキュメント)
- 課題の概要
- 課題のゴール(要件・期待される動作)
- 分かっていること
- 分からないこと・これから調査すべきこと
ここを対象課題への取り組みの拠点と定め、やや外向きな言葉遣いで記述していきます。
自分に向けてとは言いつつ、「課題のことをすっかり忘れてしまってもいいようにまとめておくぞ」という心持ちで作成しているため、実質は第三者のエンジニアへ向けるものと同じ基準と言えましょう。
この資料のメリットは、(なんのひねりもありませんが、)この調査資料の内容をそのまま各所への報告・相談に転用できることです。
チームの朝会での報告、課題チケットに対する報告、もちろん質問時に概要を伝えたい際にも、この資料をベースに内容を作成します。
コピペで十分な場面も少なくありません。
報告が必要なときになってまとめはじめるのでは時間のロスが避けられません。もし作業中の記録もよく取っていなかったとあれば、思い出すことと言語化することを同時にこなしていかなければならずハイコストです。
この資料だけは記憶の新鮮なうちに少しずつ更新し、現況に近い状態を維持しておくよう努めます。
口頭でのコミュニケーションに優れている自信のない人ほど、円滑なコミュニケーションのための道具としてドキュメントを作成する習慣づけをしてみてはいかがでしょうか。
全てのドキュメントに感謝を - 組織の資産としてのドキュメント
フレームワークや単体テストの基礎もおぼつかない初心者でありながら、順調に基礎を固めていくことがかなった要因は、先輩方の知識と手解き、そして組織内外にあまたあるドキュメントのおかげです。
新入社員のオンボーディング効率化を目的に作成されたスタートガイドは、まさしくon boardするだけで無駄なく開始地点に導いてくれるものです。2年目になっても3年目になってもたびたび参照することになるであろう確信があります。
実務として課題に取り組むさなかにも、多くの既存のドキュメントが仕様理解や不具合調査の近道となってくれました。
これから作成されるドキュメント達も将来の課題解決に役立てられるはずです。
上に挙げたスタートガイドはいまだ進化の途上であり、この夏には開発部全体でドキュメント改善を議論する場を持ちました。
私が過去の調査記録をありがたく利用させていただいているように、私の調査記録や学習ノートも組織の資産として残り、今後の開発に貢献するものとなればと望みます。
スタートガイドのようなマニュアルをいちから作るのは、たいへん時間がかかります。
しかし仕様の調査記録や学習ノートを少し外向けに整理して残すだけならば、多くの人にとってそう難しいことではないはずです。
特に新人エンジニアだからこそ残せる資料もあるでしょう。
豊富な経験を持つエンジニアだと、メモを取る間もなく通り過ぎるような典型的な処理も、私はひとつひとつ拾わなければ不安が大きい。
つまり、珍しくもない典型的な処理やライブラリの使い方をわざわざ調べる新人エンジニアは、経験則で突破できる経験者よりも、ドキュメントを残すという貢献のチャンスに恵まれていると考えます。やった!
リモートワークとドキュメント文化
近年、リモートワークが急速に普及し、テキストによる非同期コミュニケーションの検証と最適化が促進されることとなりました。
会議を除く会話のほとんどがチャットに置き換わり、コミュニケーションの非同期性が高まります。この環境におけるドキュメントの意義はこれまで述べたとおりです。
ただ、ドキュメント文化を推奨する声は2020年より前から存在しています。多くの組織がドキュメントを軽視していたわけでもないでしょう。
リモートワークがドキュメントの価値を高めたというより、リモートワークがもたらした、テキストベースの非同期コミュニケーションがドキュメントのハードルを大きく下げたというほうが正しそうです。
この追い風を受けきって、成功体験の蓄積と文化の醸成を加速させたいところです。
まとめ
情報をドキュメントにまとめる作業は、それだけで頭の中の整理に役立ちます。
また、言語化・取捨選択・並べ替えなど論理的思考の訓練にもなります。ともすれば苦手な口頭でのコミュニケーションにもその成果が現れてくれるのではと期待しています。
この記事を通して、ドキュメント作成に対する意識や期待に変わりはあったでしょうか。
自分のため、チームのため、将来の組織のための意義深さを感じられましたら幸いです。
ここまでお付き合いいただきまして、どうもありがとうございました。
(さて、時間のあるときにブログ執筆の記録をドキュメント化しよう)
弊社では採用活動を実施しています。
皆様のご応募をお待ちしております。
- 2023年度新卒採用:https://www.i3-systems.com/new-graduates/
- キャリア採用:https://www.i3-systems.com/careers/