Share
Embed
エンジニアが一生困らない ドキュメント作成の基本
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
Transcript
86 slides
-
仲田 尚央 Nakata Naohiro @naoh_nak • 本業: テクニカルライター、UXライター@SmartHR • サイドワーク:
非常勤講師@都立産業技術高専 書籍執筆 ソフトウェアのUIテキストを書いたり、ドキュメント を書いたりするお仕事をしています。 -
本書の内容 • ドキュメントの読み方を理解する • 読み手とテーマを選定する • テーマを分解する • ドキュメントの骨組みを組む •
文章を書く • わかりやすい文を書く • ChatGPTで効率良く書く • ドキュメントの構成例 本セッションのスコープ ドキュメントを書くための基礎スキル とは、テーマをもとにドキュメントの 適切な構成を組み、文章に落とし込む 技術です。 -
プログラミングと同じく設計が大切 プログラムを書く 要件定義 設計 実装 読み手とテーマの 選定 構成の設計 執筆 ドキュメントを書く
適切な設計が効率につながる • 読み手が効率良く情報を得られる • 書き手が効率良く書ける -
ユーザビリティーが高いドキュメントを書くための要素 情報の整理 情報を分解し、整理して伝える 構成 • わかりやすく • 誤解がなく • 肯定的に受け止められる
文を書く 文 見出しや文章を適切に構成し、 どこに何が書かれているかを わかりやすくする -
目標と手段 情報の整理 情報を分解し、整理して伝える 構成 • わかりやすく • 誤解がなく • 肯定的に受け止められる
文を書く 文 見出しや文章を適切に構成し、 どこに何が書かれているかを わかりやすくする Effectiveness 必要な情報を正しく得られる Efficiency 効率良く情報を得られる Satisfaction 不快さがなく、肯定的 に受け止められる 目標 手段 ユーザビリティーの高いドキュメント -
目標と手段 情報の整理 情報を分解し、整理して伝える 構成 • わかりやすく • 誤解がなく • 肯定的に受け止められる
文を書く 文 見出しや文章を適切に構成し、 どこに何が書かれているかを わかりやすくする Effectiveness 必要な情報を正しく得られる Efficiency 効率良く情報を得られる Satisfaction 不快さがなく、肯定的 に受け止められる 目標 手段 ユーザビリティーの高いドキュメント ここからは、情報の整理と構成の組み立てに 焦点を当ててお話します -
ドキュメントの階層構造 ドキュメントは階層構造を持つ • 1つのドキュメントで、1つのテーマ • 1つの見出しで、1つのサブテーマ • 1つのパラグラフで、1つの話題 テーマ サブテーマ
話題 話題 話題 話題 階層構造を取ることで、複雑な情報を分解して 伝えることができる サブテーマ -
情報を分解、整理し、ドキュメントの構成に反映する テーマ サブテーマ 話題 話題 話題 話題 サブテーマ テーマ サブテーマ
話題 話題 話題 話題 話題 話題 サブテーマ サブテーマ -
マニュアルであれば • Why(目的): ◦ 読み手にとってその機能がなぜ必要なのか • What(目標): ◦ その機能はどういうものなのか ◦
その機能でできること • How(手段): ◦ その機能をどうやって使うのか Why なぜ What 何を テーマ How どうやって -
企画書であれば • Why(目的): ◦ なぜその企画が必要なのか(目的) • What(目標): ◦ 何をするのか・何をしないのか(目標) •
How(手段): ◦ 目標をどうやって実現するのか(手段) Why なぜ What 何を テーマ How どうやって -
報告書であれば • Why(目的): ◦ なぜその活動が必要だったのか • What(結果): ◦ 活動の結果はどうだったか ◦
結果からどのような考察が得られたか • How(手段): ◦ どうやって結果を得たのか Why なぜ What 何を テーマ How どうやって -
• Why(目的): ◦ ドキュメントの目的 • What(目標): ◦ ドキュメントとは何か ◦ ドキュメントの目標
• How(手段): ◦ ドキュメントの書き方 Why なぜ What 何を テーマ How どうやって 本セッションであれば -
3つの要素を分解する(マニュアルの場合) 地域コミュニティーの形成 メッセージアプリの 公開チャット機能 Why(目的) How(機能の使い方) イベントや活動の計画 趣味や興味の共有 What(どんな機能か) チャットルームを作成する機能
管理者がルームを削除する機能 管理者が参加者を管理する機能 管理者がメッセージを削除する機能 ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者がルームを削除する機能 管理者が参加者を管理する機能 管理者がメッセージを削除する機能 ニックネームとアイコンを設定する機能 チャットルームに参加する機能 チャットルームに参加する機能 -
3つの要素を分解する(企画書の場合) 開発速度の低下 フレームワークを Reactに移行する Why(目的) How(手段) 学習コストの高さ 開発者の確保の困難さ What(目標) Reactへの移行する
移行による効果の検証 主なタスク スケジュール メンバー 必要なコスト リスクと対策 開発効率の向上 研修期間の短縮 レンダリング速度の向上 -
分解の2つのパターン テーマ サブテーマ 話題 話題 話題 話題 話題 話題 サブテーマ
サブテーマ 概要 全体 具体 部分 具体例で分解 構成要素で分解 -
全体から部分へと展開する ハードウェアであれば構成部品で、ソフトウェアであれば構成機能で分解される スマートフォン パネル タッチパネル 液晶パネル CPU メモリー ネットワークモジュール LANモジュール
Bluetooth センサー 加速度センサー ジャイロセンサー 近接センサー ・・・ -
概要から具体へと分解する スマートフォン Android スマートフォン Pixel Xperia Galaxy ・・・ iPhone iPhone
Pro Max iPhone Pro iPhone mini ・・・ -
順に説明を展開していく スマートフォン Android スマートフォン Pixel Xperia Galaxy ・・・ iPhone iPhone
Pro Max iPhone Pro iPhone mini ・・・ 段階を追って知識を付け加え ていくことが、わかりやすさ に繋がる -
メッセージアプリのマニュアルであれば メッセージアプリ の使い方 家族や友人と話す 共通の趣味や関心を持 つ人と話す チャットする 通話する ビデオ通話する コミュニティー
に参加する コミュニティー を作る 概要 具体 具体例で分解 利用目的の具体例で分解 -
メッセージアプリのマニュアルであれば メッセージアプリ の使い方 会話 連絡帳 プロフィール チャット 通話 ビデオ通話 公開チャット
非公開チャット 全体 部分 構成要素で分解 機能の構成要素で分解 -
マニュアルであれば メッセージアプリ の使い方 家族や友人と話す 共通の趣味や関心を持 つ人と話す チャットする 通話する ビデオ通話する コミュニティー
に参加する コミュニティー を作る 子供の学校の親同士で 話す場をつくりたい 自分の目的をどうすれば達成できるのか知りたいのであれば 利用目的の具体例で分解 -
マニュアルであれば メッセージアプリ の使い方 会話 連絡帳 プロフィール チャット 通話 ビデオ通話 公開チャット
非公開チャット 機能の用途や使い方を知りたいのであれば 公開チャットの管理者が できることを知りたい 機能の構成要素で分解 -
答え 読み手の目的が機能の仕様を知ることであれば、機能の構成要素で分解する プロダクトの外部仕様 機能要件 非機能要件 機能1 機能2 機能3 画面 帳票
エラー ログ セキュリティ パフォーマンス 動作環境 全体から部分へと説明を展開することで、開発者はプロダクトの全体像を把握しながら各機能を開発できる -
構成を読み手に伝える「アウトライン」 • アウトラインとは、物事のあらまし・ 大筋・概略 • ドキュメントにおけるアウトラインとは、 章・節・項などの見出しを階層的に設定、 表示したもの 例:レポートのアウトライン •
概要 • 調査の背景 • 調査の内容 ◦ データの収集 ◦ データの分析 • 調査の結果と考察 • 結論 -
アウトラインの役割(書き手にとって) ① 論理を組み立てる 例:レポートのアウトライン • 概要 • 調査の背景 • 調査の内容
◦ データの収集 ◦ データの分析 • 調査の結果と考察 • 結論 Why How What • Why(目的): ◦ なぜその調査が必要だったのか • What(結果): ◦ 調査の結果はどうだったか ◦ 結果からどのような考察が得られたか • How(手段): ◦ どうやって結果を得たのか -
分解した情報をアウトラインに仕立てるステップ 1. 要素を並べ替える テーマを分解してでき要素を、読み手に伝える順番を考えて並べ替える 2. 見出しを付ける要素を選ぶ 並べ替えた要素の中から、見出しを付けるものを選ぶ 3. 見出しを決める 本文に何が書かれているか、または本文で何が言いたいかを具体的に示す見出しを付
ける 4. 見出しだけを流して読んでみる 最後に見出しだけを流して読んでみて、どこに何が書かれているかや、ドキュメント で言いたいことをザックリ掴めることを確認する -
マニュアルのアウトラインを作ろう 地域コミュニティーの形成 メッセージアプリの 公開チャット機能 なぜ(目的) どうやって(機能の使い方) イベントや活動の計画 趣味や興味の共有 何を(どんな機能か) チャットルームを作成する機能
管理者がルームを削除する機能 管理者が参加者を管理する機能 管理者がメッセージを削除する機能 ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者がルームを削除する機能 管理者が参加者を管理する機能 管理者がメッセージを削除する機能 ニックネームとアイコンを設定する機能 チャットルームに参加する機能 チャットルームに参加する機能 -
Step1 要素を並べ替える 地域コミュニティーの形成 メッセージアプリの 公開チャット機能 なぜ(目的) どうやって(機能の使い方) イベントや活動の計画 趣味や興味の共有 何を(どんな機能か)
チャットルームを作成する機能 管理者がルームを削除する機能 管理者が参加者を管理する機能 管理者がメッセージを削除する機能 ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者がルームを削除する機能 管理者が参加者を管理する機能 管理者がメッセージを削除する機能 ニックネームとアイコンを設定する機能 チャットルームに参加する機能 チャットルームに参加する機能 次のいずれかで並べ替える • 既知から未知へ • 時系列で • 重要なものから • ニーズが大きいものから -
Step1 要素を並べ替える メッセージアプリの 公開チャット機能 どうやって(機能の使い方) 何を(どんな機能か) チャットルームを作成する機能 管理者がルームを削除する機能 管理者が参加者を管理する機能 管理者がメッセージを削除する機能
ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者がルームを削除する機能 管理者が参加者を管理する機能 管理者がメッセージを削除する機能 ニックネームとアイコンを設定する機能 チャットルームに参加する機能 チャットルームに参加する機能 地域コミュニティーの形成 なぜ(目的) イベントや活動の計画 趣味や興味の共有 既知から未知へと並べ替える -
Step1 要素を並べ替える メッセージアプリの 公開チャット機能 どうやって(機能の使い方) 何を(どんな機能か) チャットルームに参加する機能 ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者が参加者を管理する機能
管理者がルームを削除する機能 チャットルームに参加する機能 ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者が参加者を管理する機能 管理者がルームを削除する機能 管理者がメッセージを削除する機能 管理者がメッセージを削除する機能 地域コミュニティーの形成 なぜ(目的) イベントや活動の計画 趣味や興味の共有 時系列で並べ替える 時系列で並べ替える -
Step1 要素を並べ替える メッセージアプリの 公開チャット機能 どうやって(機能の使い方) 何を(どんな機能か) チャットルームに参加する機能 ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者が参加者を管理する機能
管理者がルームを削除する機能 チャットルームに参加する機能 ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者が参加者を管理する機能 管理者がルームを削除する機能 管理者がメッセージを削除する機能 管理者がメッセージを削除する機能 趣味や興味の共有 なぜ(目的) 地域コミュニティーの形成 イベントや活動の計画 ニーズの大きそうなものから並べ替える -
Step2 見出しを付ける要素を選ぶ メッセージアプリの 公開チャット機能 どうやって(機能の使い方) 何を(どんな機能か) チャットルームに参加する機能 ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者が参加者を管理する機能
管理者がルームを削除する機能 チャットルームに参加する機能 ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者が参加者を管理する機能 管理者がルームを削除する機能 管理者がメッセージを削除する機能 管理者がメッセージを削除する機能 趣味や興味の共有 なぜ(目的) 地域コミュニティーの形成 イベントや活動の計画 • 内容が多い要素、重要な 要素に見出しを付ける • 内容が少なくなりそうな 要素は他の要素と結合 内容が少なそうなので 1つの見出しでくくる 重要な要素なのでそれ ぞれに見出しを付ける -
Step2 見出しを付ける要素を選ぶ メッセージアプリの 公開チャット機能 どうやって(機能の使い方) 何を(どんな機能か) チャットルームに参加する機能 ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者が参加者を管理する機能
管理者がルームを削除する機能 チャットルームに参加する機能 ニックネームとアイコンを設定する機能 チャットルームを作成する機能 管理者が参加者を管理する機能 管理者がルームを削除する機能 管理者がメッセージを削除する機能 管理者がメッセージを削除する機能 趣味や興味の共有 なぜ(目的) 地域コミュニティーの形成 イベントや活動の計画 内容が少なそうなので 1つの見出しでくくる 重要な要素なのでそれ ぞれに見出しを付ける 公開チャット機能のマニュアルのアウトライン • 何を(どんな機能か) • 管理者ができること • なぜ(機能の利用目的) ◦ 趣味や興味の共有 ◦ 地域コミュニティーの形成 ◦ イベントや活動の計画 • どうやって(機能の使い方) ◦ チャットルームに参加する機能 ◦ ニックネームとアイコンを設定する機能 ◦ チャットルームを作成する機能 ◦ 管理者が参加者を管理する機能 ◦ 管理者がメッセージを削除する機能 ◦ 管理者がルームを削除する機能 -
Step3 見出しを決める 公開チャット機能のマニュアルのアウトライン • 何を(どんな機能か) • 管理者ができること • なぜ(機能の利用目的) ◦
趣味や興味の共有 ◦ 地域コミュニティーの形成 ◦ イベントや活動の計画 • どうやって(機能の使い方) ◦ チャットルームに参加する機能 ◦ ニックネームとアイコンを設定する機能 ◦ チャットルームを作成する機能 ◦ 管理者が参加者を管理する機能 ◦ 管理者がメッセージを削除する機能 ◦ 管理者がルームを削除する機能 公開チャット機能のマニュアルのアウトライン • 匿名で誰でも楽しめるチャットルーム • 管理者ができること • 公開チャットはこんなときに使える ◦ 共通の趣味や興味を持つ人たちと話す ◦ 地域のコミュニティーで情報交換する ◦ イベントや活動を計画する • 公開チャットの使い方 ◦ チャットルームに参加する ◦ ニックネームとアイコンを設定する ◦ チャットルームを作成する ◦ 【管理者のみ】参加者を管理する ◦ 【管理者のみ】メッセージを削除する ◦ 【管理者のみ】チャットルームを削除する 次のいずれかを示した見出しにする • 本文に何が書かれているか • 本文で何を言いたいか -
Step4 見出しだけを流して読んでみる 公開チャット機能のマニュアルのアウトライン • 匿名で誰でも楽しめるチャットルーム • 管理者ができること • 公開チャットはこんなときに使える ◦
共通の趣味や興味を持つ人たちと話す ◦ 地域のコミュニティーで情報交換する ◦ イベントや活動を計画する • 公開チャットの使い方 ◦ チャットルームに参加する ◦ ニックネームとアイコンを設定する ◦ チャットルームを作成する ◦ 【管理者のみ】参加者を管理する ◦ 【管理者のみ】メッセージを削除する ◦ 【管理者のみ】チャットルームを削除する 見出しだけを流して読んでみて、話のあら ましや流れを掴めるかどうかを確認する 話のあらましを掴むための情報は 見出しに表れていなければならない -
各パラグラフで言いたいことが見出しに結び付く 言いたいこと その理由や説明 言いたいこと その理由や説明 パラグラフ 言いたいこと その理由や説明 見出しの中全体で 言いたいこと
1つの見出し パラグラフ パラグラフ 『エンジニアが一生後悔しない ドキュメントの基本』から引用 -
話題のまとまりを意識すると書きやすくなる • 書くべきことが小さい単位で決まる 1つの「言いたいこと」をスバリを書けば良い • 話の流れを作りやすくなる 1つの見出しの中で言いたいことに結び付くよう各パラグラフの「言いたいこと」を書 けば良い • 文章を展開しやすくなる
「言いたいこと」と「その理由や説明」に分けて書くことで、パラグラフの文章を展 開しやすくなる -
パラグラフを展開する 公開チャット機能のマニュアルのアウトライン • 匿名で誰でも楽しめるチャットルーム • 管理者ができること • 公開チャットはこんなときに使える ◦ 共通の趣味や興味を持つ人たちと話す
◦ 地域のコミュニティーで情報交換する ◦ イベントや活動を計画する • 公開チャットの使い方 ◦ チャットルームに参加する ◦ ニックネームとアイコンを設定する ◦ チャットルームを作成する ◦ 【管理者のみ】参加者を管理する ◦ 【管理者のみ】メッセージを削除する ◦ 【管理者のみ】チャットルームを削除する この見出しの中を 書いてみよう -
Step1 各パラグラフで言いたいことを書く 見出し:匿名で誰でも楽しめるチャットルーム 公開チャットは、匿名で誰でも楽しめるチャット ルームです。 匿名で誰でも楽しめる チャットルーム チャットルームに 参加する機能 ニックネームとアイコ
ンを設定する機能 チャットルームを 作成する機能 まずは見出しの中で言いたい ことをズバリと言う -
Step1 各パラグラフで言いたいことを書く 匿名で誰でも楽しめる チャットルーム チャットルームに 参加する機能 ニックネームとアイコ ンを設定する機能 チャットルームを 作成する機能
見出し:匿名で誰でも楽しめるチャットルーム 公開チャットは、匿名で誰でも楽しめるチャット ルームです。 公開チャットのチャットルームには自由に参加で きます。 プライバシーも保ちながら匿名で気軽にチャット ルームに参加できることも、公開チャットの特長 です。 さらに、自分でチャットルームを作成することも できます。 続いて、テーマを分解した話題に沿って 各パラグラフで言いたいことを書いていく -
Step2 話の流れを確認する 見出し:匿名で誰でも楽しめるチャットルーム 公開チャットは、匿名で誰でも楽しめるチャット ルームです。 公開チャットのチャットルームには自由に参加で きます。 プライバシーも保ちながら匿名で気軽にチャット ルームに参加できることも、公開チャットの特長 です。
さらに、自分でチャットルームを作成することも できます。 各パラグラフで言いたいことが見出し に結び付いていることを確認する -
Step3 言いたいことの理由や説明を書き足す 見出し:匿名で誰でも楽しめるチャットルーム 公開チャットは、匿名で誰でも楽しめるチャット ルームです。趣味や興味などをテーマにしたさま ざまなチャットルームがあり、匿名で自由に参加 できます。また、自分でテーマを決めてチャット ルームを作ることもできます。 1つめのパラグラフでは全体像(後続する パラグラフの3つの話題)をそれぞれ述べる
匿名で誰でも楽しめる チャットルーム 自由にルームに 参加できる 匿名でルームに 参加できる 自由にルームを 作成できる 説明を述べる 1つめのパラグラフの文章 -
Step3 言いたいことの理由や説明を書き足す 公開チャットのチャットルームには自由に参加で きます。カテゴリーから選んだり、キーワードか で検索したりして、自分の興味に合ったチャット ルームを見つけられます。また、参加者からの招 待を受けて特定のチャットルームに参加すること もできます。 どのように自由に参加できるのかを 具体例を挙げて説明する
2つめのパラグラフの文章 チャットルームに 自由に参加できる カテゴリーから 参加する 検索して 参加する 招待を受けて 参加する 具体例を挙げる -
Step3 言いたいことの理由や説明を書き足す プライバシーを保ちながら匿名で気軽にチャット ルームに参加できることも、公開チャットの特長 です。公開チャットに参加するときには、プロ フィールの名前とは異なるニックネームやアイコ ンを設定できます。ほかの参加者に本名やプロ フィールが公開されることはありません。 なぜプライバシーを保てるのかを理由を 挙げて説明する
3つめのパラグラフの文章 プライバシーを保ち ながら参加できる ニックネームとアイ コンを設定できる 本名やプロフィール は非公開 理由を挙げる -
Step3 言いたいことの理由や説明を書き足す さらに、自分でチャットルームを作成することも できます。ルームの名前、説明、カバー画像など を設定し、ルームのテーマや雰囲気に合わせて見 た目をカスタマイズできます。また、参加ルール やガイドラインを設けることも可能です。これら の設定は、あとからいつでも変更できます。 どのようにチャットルームを作成できる のかの詳細を説明する
4つめのパラグラフの文章 自分でチャットルー ムを作成できる ルームに設定 できること 設定はあとから 変更できること 説明を述べる -
文章が完成 匿名で誰でも楽しめるチャットルーム 公開チャットは、匿名で誰でも楽しめるチャットルームです。趣味や興味などをテーマにしたさまざまなチャッ トルームがあり、匿名で自由に参加できます。また、自分でテーマを決めてチャットルームを作ることもできま す。 公開チャットのチャットルームには自由に参加できます。カテゴリーから選んだり、キーワードかで検索したり して、自分の興味に合ったチャットルームを見つけられます。また、参加者からの招待を受けて特定のチャット ルームに参加することもできます。 プライバシーを保ちながら匿名で気軽にチャットルームに参加できることも、公開チャットの特長です。公開 チャットに参加するときには、プロフィールの名前とは異なるニックネームやアイコンを設定できます。ほかの
参加者に本名やプロフィールが公開されることはありません。 さらに、自分でチャットルームを作成することもできます。ルームの名前、説明、カバー画像などを設定し、 ルームのテーマや雰囲気に合わせて見た目をカスタマイズできます。また、参加ルールやガイドラインを設ける ことも可能です。これらの設定は、あとからいつでも変更できます。 -
まとめ • わかりやすいドキュメントを効率良く書くために、ドキュメントの設計が大切 • そのために、ドキュメントのテーマを分解して整理し、ドキュメントの構成に 落とし込む • テーマはWhy(なぜ)・What(何を)・How(どうやって)の3つに分解で きる •
見出しは「本文に何が書かれているか」・「本文で何を言いたいか」を具体的 に伝えるものにする • テーマを分解した要素に沿って文章を組み立てることで、話しの筋が通り、論 理立った文章になる 本セッションや書籍の感想を是非SNSでシェアいただけると嬉しいです!