なぜドキュメントを学ぶのか

ストーリー

入社して数ヶ月が経ったある日。

「今日の打ち合わせの議事録をお願い」と先輩に頼まれた。

議事録？どう書けばいいんだろう。とりあえずメモを取ったけど、これでいいのか自信がない...。

「技術文書を書く力は、プログラミングと同じくらい大事だよ」

そう言われて、ドキュメントの書き方を学ぶことにした。

ドキュメントが必要な理由

コードだけでは伝わらない

プログラムのソースコードには「何をしているか」は書かれています。しかし、以下のことはコードだけでは分かりません。

コードだけでは分からないこと	例
なぜその実装にしたのか	「パフォーマンスのためにキャッシュを導入した」
どう使えばいいのか	「まずAを設定してからBを実行する」
何が決まったのか	「会議でこの方針に決定した」
どんな問題が起きたか	「障害が発生し、Xの手順で復旧した」

ドキュメントは「コードの意図」を伝えるための手段です。

引き継ぎに必要

あなたが作った仕組みやシステムを、他の人が使う場面は必ず来ます。

ドキュメントがない場合:
  田中さん「この機能どうやって動かすの？」
  佐藤さん「え？作った人もう辞めたから分からない...」
  → 一から調べ直すのに何日もかかる

ドキュメントがある場合:
  田中さん「この機能どうやって動かすの？」
  佐藤さん「手順書があるよ、これを見て」
  → 30分で理解できた

チームで仕事をするために

ソフトウェア開発は一人ではできません。チームで仕事をするとき、ドキュメントは共通言語になります。

議事録: 「何が決まったか」を全員が確認できる
週報: 「誰が何をしているか」をチームで把握できる
手順書: 「誰がやっても同じ結果」になる
障害報告書: 「何が起きて、どう対処したか」を記録する

ドキュメントを書けると何が良いのか

仕事の評価が上がる

ドキュメントが書けない人	ドキュメントが書ける人
口頭でしか説明できない	文書で正確に伝えられる
「あの件どうなった？」と聞かれる	記録があるので確認してもらえる
引き継ぎに時間がかかる	スムーズに引き継ぎできる
自分の成果が見えにくい	成果が文書として残る

技術力の証明になる

READMEが丁寧なOSSプロジェクトは信頼される
技術ブログを書ける人は評価が高い
設計書を書ける人は上流工程にも携われる

このミッションで学ぶこと

このミッションを完了すると、以下ができるようになります：

技術文書の種類と用途を説明できる
Markdownで文書を書ける
議事録を作成できる
週報・障害報告書を作成できる
手順書・READMEを作成できる
テンプレートを活用して効率的に文書を作成できる

全6ステップ、合計20時間 で、技術文書を書く基礎をマスターします。

まとめ

ポイント	内容
なぜ必要か	コードだけでは意図が伝わらない
引き継ぎ	ドキュメントがあれば短時間で理解できる
チーム	共通言語としてドキュメントが機能する
評価	文書力はエンジニアの重要スキル

ドキュメントが必要な理由を理解した
学ぶメリットを理解した

次のステップへ

ドキュメントの重要性は理解できましたか？

次のセクションでは、技術文書にはどんな種類があるのかを学びます。議事録、手順書、設計書... それぞれの役割を見ていきましょう。

推定読了時間: 15分