[[📒Productivityを上げるために大切な100のこと]] No85. 🥈 --- 本稿は読者として、**プログラミング言語を扱うエンジニア**を想定する。 ## ドキュメントはエンジニアにどう映るのか? 世の中にはプログラミングを好きな人が少なからず存在する。その人たちがすべて[[ドキュメンテーション]]が好きか?と言われれば、答えはもちろんNoだ。コードを書くのは好きなのに、ドキュメントは面倒くさがって書かないようなエンジニアはそれなりにいるのだ。 ## [[ドキュメンテーション]]が必要な理由 好き嫌いにかかわらず[[ドキュメンテーション]]は重要だ。主な理由として以下のようなものが挙げられる。 - 実装(actual)ではなく仕様(expected)を明確にするため - 開発言語を読めないステークホルダーとコミュニケーションするため - コードでは表現できないような内容を共有するため 『実装が常に最新なので仕様書は時間の無駄..!!』という意見も聞くが、それではコードの動きがすべて正であり開発者が神様になってしまう。また、仕様の認識合わせをするため、[[ドメインエキスパート]]のようなステークホルダーとコミュニケーションする際も、ソースコードベースで行うのは非現実だ。他にも、図を使った方が分かりやすいケースはドキュメントを書いた方が伝わりやすいだろう。 品質の高いドキュメントが用意されていれば、コミュニケーションコストは大幅に削減する。その分、コーディングに時間がさけるだろう。以前紹介した [[📗ドキュメントに書いてから答える]] でも紹介したとおりだ。 <div class="link-card-v2"> <div class="link-card-v2-site"> <img class="link-card-v2-site-icon" src="https://publish-01.obsidian.md/access/35d05cd1bf5cc500e11cc8ba57daaf88/favicon-64.png" /> <span class="link-card-v2-site-name">Minerva</span> </div> <div class="link-card-v2-title"> 📗ドキュメントに書いてから答える </div> <div class="link-card-v2-content">Slackやチャットでの質問対応は、情報の検索性や最新性を保つためにドキュメント化し、URLで回答するのが効果的です。Obsidianやドキュメンテーション設計も重要です。</div> <img class="link-card-v2-image" src="https://publish-01.obsidian.md/access/35d05cd1bf5cc500e11cc8ba57daaf88/Notes/attachments/minerva-image.webp" /> <a data-href="📗ドキュメントに書いてから答える" class="internal-link"></a> </div> %%[[📗ドキュメントに書いてから答える]]%% ## [[ドキュメンテーション]]はなぜつまらないのか? [[ドキュメンテーション]]はなぜ嫌われるのか。これは筆者の推測だが、==コーディングはクリエイティブな作業であり、[[ドキュメンテーション]]は単純作業である==と誤解されているのではないだろうか。単純作業ゆえ、つまらないと感じるのだ。 だが、本当に[[ドキュメンテーション]]は単純作業なのか。少なくとも私は、==コーディングと同等レベルに奥深い複雑な作業であると考えている==。もしそう感じないのであれば、プログラミングの初学者が命令形の単純なコードしか書けないように、[[ドキュメンテーション]]においてのスキルが不足しているのかもしれない。 ソースコードもドキュメントは、**どちらも言語を使って**書かれている。前者が[[Java]]や[[Python]]のようなものであれば、後者は日本語や英語のようなものだ。どちらにも単語や文法が存在する。 ソースコードはドキュメントに比べて、機械が多くを理解し、自動化を促進する。だからクリエイティブだと思うかもしれない。とはいえ視点を揃えれば、ドキュメントは人間が多くを理解し、その後の判断やアクションを促進するという点で同じだ。対象が機械か人間かという違いだけだ。 そのため、==コーディングの際に『実行する機械や読む人間を意識して設計を考える』という作業は、ドキュメンテーションの『実行・読む人間を意識して設計を考える』という点と比較したなら、大差がないはず==なのである。 ## インターフェースをしっかり考える ドキュメントの設計もコーディングのそれと同じだ。 コーディングではクラス、関数、変数の命名を深く考えるだろう。コードを読めば理解できるようにするためだ。 特に関数は重要なインターフェースであり、コーディングにおいてもインターフェースの設計1つでコードの可読性や拡張性が大きく変わる。[[ドキュメンテーション]]におけるインターフェースは、ファイル名、ページタイトル、見出し名などが該当するだろう。 ```markdown # 最終退出の手順 1. フロアに誰もいないことを確認する 2. 左側扉付近の換気停止ボタンと消灯ボタンを押す 3. 右側扉付近の換気停止ボタンと消灯ボタンを押す 4. 中央扉付近の換気停止ボタンと消灯ボタンを押す 5. カードでドアを開き外に出る 6. 警戒ボタンを押す 7. カードをかざす 8. 『警戒がセットされました』というガイダンスを確認する ``` [[ドキュメンテーション]]で設計を考えない場合、上記のように手順を列挙したものになりやすい。一見丁寧に見えるかもしれないが、前提知識のある人からすればこの書き方は冗長だろう。main関数にすべての処理を書くようなものだ。 このドキュメントは次のようにインターフェースを分割できる。ファイルは[[Markdown]]を想定しているが[[Obsidian]]と同様に[[wikiリンク]]が使えるものとする。 ```markdown:電源と換気を停止.md 1. 左側扉付近の換気停止ボタンと消灯ボタンを押す 2. 右側扉付近の換気停止ボタンと消灯ボタンを押す 3. 中央扉付近の換気停止ボタンと消灯ボタンを押す ``` ```markdown:警戒をセット.md 1. 警戒ボタンを押す 2. カードをかざす 3. 『警戒がセットされました』というガイダンスを確認する ``` ```markdown:最終退出の手順.md 1. フロアに誰もいないことを確認してから、[[電源と換気を停止]]する 2. 外で出て[[警戒をセット]]する ``` 何度か経験のある人がチェックリストと使うのであれば、この方が見落とすリスクも低い。分からない人はリンク先に遷移して確認すればいいだけだ。また、==電源と換気を停止する方法が変わったときも、`電源と換気を停止.md` のみ修正すれば、参照しているすべてのドキュメントの整合性が保てる==。これらの思想は[[Evergreen Notes]]に書かれた、[[Evergreen NotesのタイトルはAPIのようなもの]] が参考になる。 ## 開発のように[[ドキュメンテーション]]を設計する コーディングも[[ドキュメンテーション]]も本質は同じだ。扱う言語と関わるモノが少し違うだけに過ぎない。それゆえ、==可読性や拡張性に優れたコードを書く人は、可読性や拡張性に優れたドキュメントを書くことができる==。逆もまた然りだ。 今回はインターフェースについて触れたが以下も同様である。 - [[📗ドキュメントのキャッシュ戦略を考える]] すべてをお話しすると長くなるため、また別の機会に。