Upgrade to PRO for Only $50/Year—Limited-Time Offer! 🔥

エンジニアが一生困らない ドキュメント作成の基本

エンジニアが一生困らない ドキュメント作成の基本

Forkwell Libraryでのセッション資料です。書籍『エンジニアが一生困らない ドキュメント作成の基本」からポイントを絞って解説しています。
良ければご購入くださると嬉しいです。
書籍:https://www.socym.co.jp/book/post-19000
セッションの録画:https://www.youtube.com/live/lTsfCzqeHQA?si=99WgqUPigftGmPL0
X:https://x.com/naoh_nak

Naohiro Nakata

November 08, 2024
Tweet

More Decks by Naohiro Nakata

Other Decks in Technology

Transcript

  1. 仲田 尚央 Nakata Naohiro @naoh_nak • 本業: テクニカルライター、UXライター@SmartHR • サイドワーク:

    非常勤講師@都立産業技術高専 書籍執筆 ソフトウェアのUIテキストを書いたり、ドキュメント を書いたりするお仕事をしています。
  2. 本書の内容 • ドキュメントの読み方を理解する • 読み手とテーマを選定する • テーマを分解する • ドキュメントの骨組みを組む •

    文章を書く • わかりやすい文を書く • ChatGPTで効率良く書く • ドキュメントの構成例 本セッションのスコープ ドキュメントを書くための基礎スキル とは、テーマをもとにドキュメントの 適切な構成を組み、文章に落とし込む 技術です。
  3. プログラミングと同じく設計が大切 プログラムを書く 要件定義 設計 実装 読み手とテーマの 選定 構成の設計 執筆 ドキュメントを書く

    適切な設計が効率につながる • 読み手が効率良く情報を得られる • 書き手が効率良く書ける
  4. 目標と手段 情報の整理 情報を分解し、整理して伝える 構成 • わかりやすく • 誤解がなく • 肯定的に受け止められる

    文を書く 文 見出しや文章を適切に構成し、 どこに何が書かれているかを わかりやすくする Effectiveness 必要な情報を正しく得られる Efficiency 効率良く情報を得られる Satisfaction 不快さがなく、肯定的 に受け止められる 目標 手段 ユーザビリティーの高いドキュメント
  5. 目標と手段 情報の整理 情報を分解し、整理して伝える 構成 • わかりやすく • 誤解がなく • 肯定的に受け止められる

    文を書く 文 見出しや文章を適切に構成し、 どこに何が書かれているかを わかりやすくする Effectiveness 必要な情報を正しく得られる Efficiency 効率良く情報を得られる Satisfaction 不快さがなく、肯定的 に受け止められる 目標 手段 ユーザビリティーの高いドキュメント ここからは、情報の整理と構成の組み立てに 焦点を当ててお話します
  6. マニュアルであれば • Why(目的): ◦ 読み手にとってその機能がなぜ必要なのか • What(目標): ◦ その機能はどういうものなのか ◦

    その機能でできること • How(手段): ◦ その機能をどうやって使うのか Why なぜ What 何を テーマ How どうやって
  7. 企画書であれば • Why(目的): ◦ なぜその企画が必要なのか(目的) • What(目標): ◦ 何をするのか・何をしないのか(目標) •

    How(手段): ◦ 目標をどうやって実現するのか(手段) Why なぜ What 何を テーマ How どうやって
  8. 報告書であれば • Why(目的): ◦ なぜその活動が必要だったのか • What(結果): ◦ 活動の結果はどうだったか ◦

    結果からどのような考察が得られたか • How(手段): ◦ どうやって結果を得たのか Why なぜ What 何を テーマ How どうやって
  9. • Why(目的): ◦ ドキュメントの目的 • What(目標): ◦ ドキュメントとは何か ◦ ドキュメントの目標

    • How(手段): ◦ ドキュメントの書き方 Why なぜ What 何を テーマ How どうやって 本セッションであれば
  10. 3つの要素を分解する(マニュアルの場合) 地域コミュニティーの形成 メッセージアプリの 公開チャット機能 Why(目的) How(機能の使い方) イベントや活動の計画 趣味や興味の共有 What(どんな機能か) チャットルームを作成する機能

    管理者がルームを削除する機能 管理者が参加者を管理する機能 管理者がメッセージを削除する機能 ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者がルームを削除する機能 管理者が参加者を管理する機能 管理者がメッセージを削除する機能 ニックネームとアイコンを設定する機能 チャットルームに参加する機能 チャットルームに参加する機能
  11. 3つの要素を分解する(企画書の場合) 開発速度の低下 フレームワークを Reactに移行する Why(目的) How(手段) 学習コストの高さ 開発者の確保の困難さ What(目標) Reactへの移行する

    移行による効果の検証 主なタスク スケジュール メンバー 必要なコスト リスクと対策 開発効率の向上 研修期間の短縮 レンダリング速度の向上
  12. 分解の2つのパターン テーマ サブテーマ 話題 話題 話題 話題 話題 話題 サブテーマ

    サブテーマ 概要 全体 具体 部分 具体例で分解 構成要素で分解
  13. 順に説明を展開していく スマートフォン Android スマートフォン Pixel Xperia Galaxy ・・・ iPhone iPhone

    Pro Max iPhone Pro iPhone mini ・・・ 段階を追って知識を付け加え ていくことが、わかりやすさ に繋がる
  14. マニュアルであれば メッセージアプリ の使い方 家族や友人と話す 共通の趣味や関心を持 つ人と話す チャットする 通話する ビデオ通話する コミュニティー

    に参加する コミュニティー を作る 子供の学校の親同士で 話す場をつくりたい 自分の目的をどうすれば達成できるのか知りたいのであれば 利用目的の具体例で分解
  15. マニュアルであれば メッセージアプリ の使い方 会話 連絡帳 プロフィール チャット 通話 ビデオ通話 公開チャット

    非公開チャット 機能の用途や使い方を知りたいのであれば 公開チャットの管理者が できることを知りたい 機能の構成要素で分解
  16. 答え 読み手の目的が機能の仕様を知ることであれば、機能の構成要素で分解する プロダクトの外部仕様 機能要件 非機能要件 機能1 機能2 機能3 画面 帳票

    エラー ログ セキュリティ パフォーマンス 動作環境 全体から部分へと説明を展開することで、開発者はプロダクトの全体像を把握しながら各機能を開発できる
  17. アウトラインの役割(書き手にとって) ① 論理を組み立てる 例:レポートのアウトライン • 概要 • 調査の背景 • 調査の内容

    ◦ データの収集 ◦ データの分析 • 調査の結果と考察 • 結論 Why How What • Why(目的): ◦ なぜその調査が必要だったのか • What(結果): ◦ 調査の結果はどうだったか ◦ 結果からどのような考察が得られたか • How(手段): ◦ どうやって結果を得たのか
  18. マニュアルのアウトラインを作ろう 地域コミュニティーの形成 メッセージアプリの 公開チャット機能 なぜ(目的) どうやって(機能の使い方) イベントや活動の計画 趣味や興味の共有 何を(どんな機能か) チャットルームを作成する機能

    管理者がルームを削除する機能 管理者が参加者を管理する機能 管理者がメッセージを削除する機能 ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者がルームを削除する機能 管理者が参加者を管理する機能 管理者がメッセージを削除する機能 ニックネームとアイコンを設定する機能 チャットルームに参加する機能 チャットルームに参加する機能
  19. Step1 要素を並べ替える 地域コミュニティーの形成 メッセージアプリの 公開チャット機能 なぜ(目的) どうやって(機能の使い方) イベントや活動の計画 趣味や興味の共有 何を(どんな機能か)

    チャットルームを作成する機能 管理者がルームを削除する機能 管理者が参加者を管理する機能 管理者がメッセージを削除する機能 ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者がルームを削除する機能 管理者が参加者を管理する機能 管理者がメッセージを削除する機能 ニックネームとアイコンを設定する機能 チャットルームに参加する機能 チャットルームに参加する機能 次のいずれかで並べ替える • 既知から未知へ • 時系列で • 重要なものから • ニーズが大きいものから
  20. Step1 要素を並べ替える メッセージアプリの 公開チャット機能 どうやって(機能の使い方) 何を(どんな機能か) チャットルームを作成する機能 管理者がルームを削除する機能 管理者が参加者を管理する機能 管理者がメッセージを削除する機能

    ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者がルームを削除する機能 管理者が参加者を管理する機能 管理者がメッセージを削除する機能 ニックネームとアイコンを設定する機能 チャットルームに参加する機能 チャットルームに参加する機能 地域コミュニティーの形成 なぜ(目的) イベントや活動の計画 趣味や興味の共有 既知から未知へと並べ替える
  21. Step1 要素を並べ替える メッセージアプリの 公開チャット機能 どうやって(機能の使い方) 何を(どんな機能か) チャットルームに参加する機能 ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者が参加者を管理する機能

    管理者がルームを削除する機能 チャットルームに参加する機能 ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者が参加者を管理する機能 管理者がルームを削除する機能 管理者がメッセージを削除する機能 管理者がメッセージを削除する機能 地域コミュニティーの形成 なぜ(目的) イベントや活動の計画 趣味や興味の共有 時系列で並べ替える 時系列で並べ替える
  22. Step1 要素を並べ替える メッセージアプリの 公開チャット機能 どうやって(機能の使い方) 何を(どんな機能か) チャットルームに参加する機能 ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者が参加者を管理する機能

    管理者がルームを削除する機能 チャットルームに参加する機能 ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者が参加者を管理する機能 管理者がルームを削除する機能 管理者がメッセージを削除する機能 管理者がメッセージを削除する機能 趣味や興味の共有 なぜ(目的) 地域コミュニティーの形成 イベントや活動の計画 ニーズの大きそうなものから並べ替える
  23. Step2 見出しを付ける要素を選ぶ メッセージアプリの 公開チャット機能 どうやって(機能の使い方) 何を(どんな機能か) チャットルームに参加する機能 ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者が参加者を管理する機能

    管理者がルームを削除する機能 チャットルームに参加する機能 ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者が参加者を管理する機能 管理者がルームを削除する機能 管理者がメッセージを削除する機能 管理者がメッセージを削除する機能 趣味や興味の共有 なぜ(目的) 地域コミュニティーの形成 イベントや活動の計画 • 内容が多い要素、重要な 要素に見出しを付ける • 内容が少なくなりそうな 要素は他の要素と結合 内容が少なそうなので 1つの見出しでくくる 重要な要素なのでそれ ぞれに見出しを付ける
  24. Step2 見出しを付ける要素を選ぶ メッセージアプリの 公開チャット機能 どうやって(機能の使い方) 何を(どんな機能か) チャットルームに参加する機能 ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者が参加者を管理する機能

    管理者がルームを削除する機能 チャットルームに参加する機能 ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者が参加者を管理する機能 管理者がルームを削除する機能 管理者がメッセージを削除する機能 管理者がメッセージを削除する機能 趣味や興味の共有 なぜ(目的) 地域コミュニティーの形成 イベントや活動の計画 内容が少なそうなので 1つの見出しでくくる 重要な要素なのでそれ ぞれに見出しを付ける 公開チャット機能のマニュアルのアウトライン • 何を(どんな機能か) • 管理者ができること • なぜ(機能の利用目的) ◦ 趣味や興味の共有 ◦ 地域コミュニティーの形成 ◦ イベントや活動の計画 • どうやって(機能の使い方) ◦ チャットルームに参加する機能 ◦ ニックネームとアイコンを設定する機能 ◦ チャットルームを作成する機能 ◦ 管理者が参加者を管理する機能 ◦ 管理者がメッセージを削除する機能 ◦ 管理者がルームを削除する機能
  25. Step3 見出しを決める 公開チャット機能のマニュアルのアウトライン • 何を(どんな機能か) • 管理者ができること • なぜ(機能の利用目的) ◦

    趣味や興味の共有 ◦ 地域コミュニティーの形成 ◦ イベントや活動の計画 • どうやって(機能の使い方) ◦ チャットルームに参加する機能 ◦ ニックネームとアイコンを設定する機能 ◦ チャットルームを作成する機能 ◦ 管理者が参加者を管理する機能 ◦ 管理者がメッセージを削除する機能 ◦ 管理者がルームを削除する機能 公開チャット機能のマニュアルのアウトライン • 匿名で誰でも楽しめるチャットルーム • 管理者ができること • 公開チャットはこんなときに使える ◦ 共通の趣味や興味を持つ人たちと話す ◦ 地域のコミュニティーで情報交換する ◦ イベントや活動を計画する • 公開チャットの使い方 ◦ チャットルームに参加する ◦ ニックネームとアイコンを設定する ◦ チャットルームを作成する ◦ 【管理者のみ】参加者を管理する ◦ 【管理者のみ】メッセージを削除する ◦ 【管理者のみ】チャットルームを削除する 次のいずれかを示した見出しにする • 本文に何が書かれているか • 本文で何を言いたいか
  26. Step4 見出しだけを流して読んでみる 公開チャット機能のマニュアルのアウトライン • 匿名で誰でも楽しめるチャットルーム • 管理者ができること • 公開チャットはこんなときに使える ◦

    共通の趣味や興味を持つ人たちと話す ◦ 地域のコミュニティーで情報交換する ◦ イベントや活動を計画する • 公開チャットの使い方 ◦ チャットルームに参加する ◦ ニックネームとアイコンを設定する ◦ チャットルームを作成する ◦ 【管理者のみ】参加者を管理する ◦ 【管理者のみ】メッセージを削除する ◦ 【管理者のみ】チャットルームを削除する 見出しだけを流して読んでみて、話のあら ましや流れを掴めるかどうかを確認する 話のあらましを掴むための情報は 見出しに表れていなければならない
  27. パラグラフを展開する 公開チャット機能のマニュアルのアウトライン • 匿名で誰でも楽しめるチャットルーム • 管理者ができること • 公開チャットはこんなときに使える ◦ 共通の趣味や興味を持つ人たちと話す

    ◦ 地域のコミュニティーで情報交換する ◦ イベントや活動を計画する • 公開チャットの使い方 ◦ チャットルームに参加する ◦ ニックネームとアイコンを設定する ◦ チャットルームを作成する ◦ 【管理者のみ】参加者を管理する ◦ 【管理者のみ】メッセージを削除する ◦ 【管理者のみ】チャットルームを削除する この見出しの中を 書いてみよう
  28. Step1 各パラグラフで言いたいことを書く 匿名で誰でも楽しめる チャットルーム チャットルームに 参加する機能 ニックネームとアイコ ンを設定する機能 チャットルームを 作成する機能

    見出し:匿名で誰でも楽しめるチャットルーム 公開チャットは、匿名で誰でも楽しめるチャット ルームです。 公開チャットのチャットルームには自由に参加で きます。 プライバシーも保ちながら匿名で気軽にチャット ルームに参加できることも、公開チャットの特長 です。 さらに、自分でチャットルームを作成することも できます。 続いて、テーマを分解した話題に沿って 各パラグラフで言いたいことを書いていく
  29. 文章が完成 匿名で誰でも楽しめるチャットルーム 公開チャットは、匿名で誰でも楽しめるチャットルームです。趣味や興味などをテーマにしたさまざまなチャッ トルームがあり、匿名で自由に参加できます。また、自分でテーマを決めてチャットルームを作ることもできま す。 公開チャットのチャットルームには自由に参加できます。カテゴリーから選んだり、キーワードかで検索したり して、自分の興味に合ったチャットルームを見つけられます。また、参加者からの招待を受けて特定のチャット ルームに参加することもできます。 プライバシーを保ちながら匿名で気軽にチャットルームに参加できることも、公開チャットの特長です。公開 チャットに参加するときには、プロフィールの名前とは異なるニックネームやアイコンを設定できます。ほかの

    参加者に本名やプロフィールが公開されることはありません。 さらに、自分でチャットルームを作成することもできます。ルームの名前、説明、カバー画像などを設定し、 ルームのテーマや雰囲気に合わせて見た目をカスタマイズできます。また、参加ルールやガイドラインを設ける ことも可能です。これらの設定は、あとからいつでも変更できます。
  30. まとめ • わかりやすいドキュメントを効率良く書くために、ドキュメントの設計が大切 • そのために、ドキュメントのテーマを分解して整理し、ドキュメントの構成に 落とし込む • テーマはWhy(なぜ)・What(何を)・How(どうやって)の3つに分解で きる •

    見出しは「本文に何が書かれているか」・「本文で何を言いたいか」を具体的 に伝えるものにする • テーマを分解した要素に沿って文章を組み立てることで、話しの筋が通り、論 理立った文章になる 本セッションや書籍の感想を是非SNSでシェアいただけると嬉しいです!