俺のドキュメントライティング

IT系のライターになって30年以上、マニュアルや技術ブログなど多彩なコンテンツを作ってきました。そこで私なりに「分かりやすいドキュメントの書き方」をまとめてみました。

マニュアルや技術ブログなどIT系の文書を書きたい人、文書作成をサポートする人などに参考になればと思います。

Transcript

1. 俺のドキュメントライティング 分かりやすい文章を書くための構造と手順 可知 豊 1
2. ◼ 対象となる人 – マニュアルや技術ブログなどIT系の文書を書きたい人 – 文書作成をサポートする人 ◼ 主な内容 – ドキュメントがどのような構造を持っているか – どんな手順でドキュメントを制作するか – AI活用に役立てるには 2
3. 自己紹介 ◼ 可知 豊（かち ゆたか） ◼ さくらインターネット – テクニカルコミュニケーションチーム所属 – クラウド事業のマニュアル制作 – マーケティングコンテンツの作成支援 3
4. テクニカルライター歴 30年以上 もともとハードウェアエンジニアとして、PCの設計に従事 1993年ごろに商業誌デビュー ◼ パソコン解説の雑誌・書籍 ◼ 秋葉原でパソコンのデモンストレータ ◼ パソコン研修（企画、制作、講師） ◼ オープンソースのコミュニティ活動 ◼ パッケージソフトのマーケティング業務 ◼ IT系メディアの記事ライティング ◼ プログラミング学習の動画制作 ◼ スタートアップでいろいろ 1998 コンテンツマーケティング コミュニティマーケティング 4
5. 誰でもドキュメントを書く時代 ドキュメント = 文書・資料 ◼ マニュアル ◼ 技術ブログ ◼ マーケティング用記事 ◼ 研修用コンテンツ ◼ スライド ◼ 動画の台本 ◼ テクニカルライター（専門スタッフ）として 読み手にきちんと伝わる品質にしたい 5
6. いいコンテンツが作れると、いろいろなところで役に立つ どこに行っても、いいコンテンツを作るには？ 6
7. 構造：文書の４つの基本レベル 文書の企画 • テーマ：クラウド開発 • 対象読者：技術者 • 目的：自社開発の参考に ▼ • 形式：システム構築事例 構成（セクションの集まり） ◼ 技術的な背景と課題 ◼ 要件の説明 段落 ◼ アーキテクチャ ◼ 開発プロセス ◼ 運用のコツ 段落 段落 文 段落 HANA Cloudは仮想サーバーを中心を とした「インフラ提供型」のサービス でした。 段落 自由度が高い一方で、開発と運用負担 が大きくなっていました。 現在のサービスはクラウドネイティブ 基盤へと進化しています。 7
8. 作業手順：構造に合わせて、順番に進める 1. 文書の企画を決める 2. 文書全体の構成をアウトラインで組み立て 3. 何を書くかを段落単位で整理する 4. 読みやすいよう、文をみがく 8
9. わかりやすい文章術 みたいな話になると "どう文を書くか"になりがち わかりやすさのためには、企画とアウトラインが重要 9
10. 手順1. 最初に、文書の企画を決める 文書の企画 • テーマ：クラウド開発 • 対象読者：技術者 • 目的：自社開発の参考に ▼ • 形式：システム構築事例 構成（セクションの集まり） ◼ 技術的な背景と課題 ◼ 要件の説明 段落 ◼ アーキテクチャ ◼ 開発プロセス ◼ 運用のコツ 段落 段落 文 段落 HANA Cloudは仮想サーバーを中心を とした「インフラ提供型」のサービス でした。 段落 自由度が高い一方で、開発と運用負担 が大きくなっていました。 現在のサービスはクラウドネイティブ 基盤へと進化しています。 10
11. 手順1. 最初に、文書の企画を決める ◼ 文書のテーマ：どんな内容を取り上げるか ◼ 対象読者：いつ誰に、この文書を読んでもらうか ◼ 文書の目的： – どんな情報・メッセージを受け取ってもらうか – 読んだ後、読み手に何をしてもらうか 11
12. マニュアルの代表的な形式 ◼ リファレンス ◼ 機能ガイド／開発ガイド ◼ クイックスタート／導入ガイド ◼ チュートリアル ◼ サンプル／作例 ◼ よくある質問と回答 同じ製品・サービスでも 読者の目的や状況によって 適した形式は変わる 12
13. 技術ブログの代表的な形式 ◼ 比較・まとめ記事 ◼ ケーススタディ・導入事例 ◼ 課題解決の解説記事 ◼ 技術解説 ◼ チュートリアル記事 記事の役割と目的に合わせて 公開する順番を調整する 13
14. 手順2. 文書全体の構成をアウトラインで組み立て 文書の企画 • テーマ：クラウド開発 • 対象読者：技術者 • 目的：自社開発の参考に ▼ • 形式：システム構築事例 構成（セクションの集まり） ◼ 技術的な背景と課題 ◼ 要件の説明 段落 ◼ アーキテクチャ ◼ 開発プロセス ◼ 運用のコツ 段落 段落 文 段落 HANA Cloudは仮想サーバーを中心を とした「インフラ提供型」のサービス でした。 段落 自由度が高い一方で、開発と運用負担 が大きくなっていました。 現在のサービスはクラウドネイティブ 基盤へと進化しています。 14
15. 手順2. アウトラインで、文書全体の構成を組み立て アウトラインとは： 1つの文書にどのような順番で情報を並べるか、 セクション単位で整理したもの。 目次案・構成案と呼ぶ場合もある。 15
16. アウトライン例：リファレンスマニュアル リファレンスなので 全コマンドで共通の見出し順 git-addのコマンドリファレンス 16
17. アウトライン例：技術ブログの解説記事 ◼ 技術の概要：技術が解決する問題や、どんな場面で使われるかを簡潔に説明 ◼ 調べた背景と理由：その技術を調べるきっかけや、抱えていた課題 ◼ 仕組み・内部構造：コア概念や内部コンポーネントを整理して理解の土台を作る ◼ 処理の流れ：内部コンポーネントがどう連携するのか、動作の流れを示す ◼ 利用例：最小構成の実装サンプルや、よく使う典型パターンを紹介する ◼ メリット・デメリット：使うと嬉しい点と、向かない場面を整理する ◼ 他技術との比較：似た技術との違いや、採用判断のポイントをまとめる 17
18. アウトライン例：技術ブログの事例記事 ◼ 背景と課題： なぜ作る必要があったのか、どんな課題があったのか ◼ 要件の説明： 機能要件・非機能要件・制約条件 ◼ 設計方針： アーキテクチャ選定理由、採用技術の比較 ◼ 開発手順： 実際の作業ログ、構築ステップ ◼ トラブル対策：ハマったところ、回避策 ◼ 成果と効果： パフォーマンス改善、運用コスト削減など ◼ 今後の展望： 改善ポイント、追加予定の機能 18
19. 同じ種類の文書では、 見出しの並び方をアウトラインの参考にできる。 代表的な記事を調べたり、AIに出力させたりして、 定番の並べ方を出発点に、読者と目的に応じて調整する。 19
20. アウトラインの書き方 見出し案を順番に並べる ◼ アウトライン作成中は、仮の見出しでOK ◼ 読者に伝わりやすいよう、基本から応用、全体から細部へと並べる ◼ 見出しの下に、そのセクションで書きたい内容を箇条書きでメモする ◼ 見出しの階層は、1-3を目安に。深くしすぎない 20
21. アウトラインの例 完成版とは順番が異なる 文末表現は、まだ整えていない 21
22. 重要なのは、見出しの順番 ◼ 定番の並べ方を使う ◼ 読者と目的に合わせて調整する 文書全体の構成が決まったら 材料を確認しよう 22
23. 実際に書いていくときのポイント 23
24. 「文として何を書くか」(What)と 「文としてどう表現するか」(How)を 分けて作業する 24
25. 手順3. 何を書くかを段落単位で整理する 文書の企画 • テーマ：クラウド開発 • 対象読者：技術者 • 目的：自社開発の参考に ▼ • 形式：システム構築事例 構成（セクションの集まり） ◼ 技術的な背景と課題 段落 ◼ 要件の説明 ◼ アーキテクチャ 段落 ◼ 開発プロセス ◼ 運用のコツ 段落 段落 段落 文 HANA Cloudは仮想サーバーを中心を とした「インフラ提供型」のサービス でした。 自由度が高い一方で、開発と運用負担 が大きくなっていました。 現在のサービスはクラウドネイティブ 基盤へと進化しています。 25
26. 手順3. 段落単位で、何を書くかを整理する ◼ パラグラフライティング ◼ パラグラフの組み立て方 ◼ 段落の具体例 ◼ 文書全体を段落の展開で組み立てる 26
27. パラグラフライティング 段落で、話題ごとに複数の文をまとめる 段落 → 段落 → 段落 → Webシステムの処理能力 を向上させる仕組み - ロードバランサー - キャッシュ - サーバーの分離 27
28. パラグラフの組み立て方 ◼ 話題を一つに決める(1段落に、1つの主題) この段落で「何を伝えるか」をひとつにしぼる。 ◼ 1行目に、主題を表す文を書く 段落の最初に、その段落の中心となる内容（主題）を一文で示す。 読み手に「これから何が語られるか」を明確に伝える役割。 ◼ 続けて、主題を補強する、いくつかの展開文を書く 主題文を説明・具体例・理由・補足などで広げる。 展開文は複数あってよいが、すべて主題に関連していることが重要。 ◼ 最後に、段落のまとめとなる結語文を書く 主題文＋展開文で述べた内容を簡潔に整理する。 これは、省略してもOK。 28
29. 段落の具体例 - イチゴをほめる！ フルーツのレシピ本 を想定しています 主題文：<イチゴは、素晴らしい！> 展開文 1：<いちごには、おいしいデザートがたくさんある> 展開文 2：<イチゴは、気軽に食べれる> 展開文 3：<イチゴは、個性的なフルーツです> 結語文：<イチゴには、いいところがたくさんある> 文章にする前のメモ 29
30. 複数の主題を束ねて、階層構造を作る 主題文：<イチゴは、素晴らしい！> 展開文 1：<いちごには、おいしいデザートがたくさんある> 展開文 2：<イチゴは、気軽に食べれる> 展開文 3：<イチゴは、個性的なフルーツです> 結語文：<イチゴには、いいところがたくさんある> 文章にする前のメモ 30
31. 展開文をさらにパラグラフライティング１ 主題文：<いちごには、おいしいデザートがたくさんある> 展開文 1：<ショートケーキ> 展開文 2：<いちごタルト> 展開文 3：<いちご大福> 結語文：<この他にも、おいしいデザートがたくさんある> 文章にする前のメモ 31
32. 展開文をさらにパラグラフライティング2 主題文：<イチゴは、気軽に食べれる> 展開文 1：<デザートに入ってる> 展開文 2：<ジャムとしてパンに塗る> 展開文 3：<もちろん、そのままでも> 結語文：<イチゴは、気軽に食べる方法が色々> 文章にする前のメモ 32
33. 展開文をさらにパラグラフライティング3 主題文：<イチゴは、個性的なフルーツだ> 展開文 1：<赤色が鮮やか> 展開文 2：<つりがね型の独特の形> 展開文 3：<小さな黄色の種と、緑色のヘタがアクセント> 結語文：<独特の色と形で、みんなの人気者> 文章にする前のメモ 33
34. 文書全体を段落の展開で組み立てる 主題 1：<イチゴは、素晴らしい！> 主張の 全体像を示す 展開文 1-1：<イチゴには、おいしいデザートがたくさんある> 展開文 1-2：<イチゴは、気軽に食べられる> 展開文 1-3：<イチゴは、個性的なフルーツです> 展開文1-1を掘り下げる → 主題文 2：<イチゴには、おいしいデザートがたくさんある> 展開文 2-1：<ショートケーキ> 具体例を示す 展開文 2-2：<いちごタルト> 展開文 2-3：<いちご大福> 結語文 2：<この他にも、おいしいデザートがたくさんある> • • • 文章にする前のメモ 34
35. 文書全体を段落の展開で組み立てる 展開文 1-2を掘り下げる → 主題文 3：<いちごは気軽に食べれる> 展開文 3-1：<デザートに入っている> 展開文 3-2：<ジャムとしてパンに塗る> 展開文 3-3：<もちろん、そのままでも> 具体例を示す 結語文 3：<イチゴには、気軽に食べる方法がいろいろある> 展開文 1-3を掘り下げる → 主題文 4：<イチゴは、個性的なフルーツだ> 展開文 4-1：<赤色が鮮やか> 展開文 4-2：<つりがね型の独特のフォルム> 展開文 4-3：<小さな黄色の種と、緑色のヘタがアクセント> 結語文 4：<独特の色と形で、みんなの人気者> 主張を繰り返す 全体のまとめ → 結語文 1：<イチゴには、いいところがたくさんある> 文章にする前のメモ 35
36. 段落を整理するポイントは、 「文として何を書くか」(What)に 集中すること 36
37. 手順4. 読みやすいよう文をみがく 文書の企画 • テーマ：クラウド開発 • 対象読者：技術者 • 目的：自社開発の参考に ▼ • 形式：システム構築事例 構成（セクションの集まり） ◼ 技術的な背景と課題 ◼ 要件の説明 段落 ◼ アーキテクチャ ◼ 開発プロセス ◼ 運用のコツ 段落 段落 文 段落 HANA Cloudは仮想サーバーを中心を とした「インフラ提供型」のサービス でした。 段落 自由度が高い一方で、開発と運用負担 が大きくなっていました。 現在のサービスはクラウドネイティブ 基盤へと進化しています。 37
38. 手順4. 読みやすいよう、文をみがく 主題文：<イチゴには、おいしいデザートがたくさんある> 展開文 1：<ショートケーキ> 展開文 2：<いちごタルト> 展開文 3：<いちご大福> 結語文：<この他にも、おいしいデザートがたくさんある> イチゴを使ったデザートには、さまざまな種類があります。たと えば、ショートケーキやイチゴタルト、イチゴ大福などです。こ の他にも、おいしいデザートがたくさんあります。 38
39. イチゴには、おいしいデザートがたくさんあります。ショー トケーキは、ふんわり白いスポンジに赤いイチゴが映える王 道の華やかさ。軽い生クリームと甘酸っぱさが優しく溶け合 います。つややかなイチゴがぎっしり並ぶいちごタルトは、 サクッと香ばしい土台と濃厚クリームが果実の酸味を引き立 てます。いちご大福は、お餅の白さにイチゴの赤がのぞく素 朴な可愛さ。柔らかな餅と餡の甘みが、ジューシーな酸味を 包み込むように広がります。この他にも、イチゴには、おい しいデザートがたくさんあります。 39
40. 文章を分かりやすくする定番テクニック ◼ 1文はできるだけ短く ◼ 否定形を最小限にする ◼ 受動体より能動体を使う ◼ 受け身を使っても自然な文 ◼ 修飾する語は近くに置く ◼ 技術用語の表現 文章テクニックは、 ルールというより ベストプラクティス(お手本) ◼ 箇条書きや表・図をうまく使う ◼ 見出しをキャッチーに書き直す 40
41. まとめ：構造と手順を明確にする効果 ◼ ドキュメント作成のブラックボックス化を解消 ◼ 慣れていない状況で、小さく分解してやり方を説明できる ◼ どこが苦手か、どこでつまずいているか、 小さな課題として対処できる ◼ コンテンツの種類が変わったときにも、応用しやすい 41
42. AIを活用する 42
43. AIを活用する ◼ スタイルの分析 ◼ 企画と調査の準備 ◼ 実際の執筆（下書き） ◼ 文書チェック 43
44. プロンプト：スタイルを分析する ➢ 次の企業のマニュアルを調査して、構成と内容の特徴を教 えて ◼ AAAA社 ◼ BBBB社 ◼ CCCC社 ➢ 次のマニュアルを調査して、スタイルと特徴を教えて ◼ 対象マニュアル：URL ◼ サービス名 44
45. プロンプト：取材の質問票を作る ➢ システム開発事例のインタビュー記事を作成します。 次の条件で、インタビューの質問票を作成して。 ◼ 開発システムの概要：B2B向けWeb広告管理システム ◼ インタビュー相手：開発プロジェクトのプロジェクトマネージャ ◼ 記事の目的：開発を担当した当社のシステム開発力をアピールしたい 45
46. プロンプト：記事の作成 ➢ 以下のインタビュー文字起こしを基に、読者にとって読みやすく、魅力的で、かつコラム記事 を執筆してください。 【必須要件】 - 読者ターゲットはIT企業のマーケティング担当者を想定する。 - 文字起こしの口語表現や冗長な部分を削除し、読みやすい文章に整える。 - 用語や固有名詞は一貫性を保ち、必要に応じて補足説明を加える。 - 引用と要約を組み合わせ、発言者の個性を活かしつつテンポよく展開する。 - ITトレンドや業界背景と関連づけて読者に価値を提供する。 - 数値・技術用語は正確に表記する。 • • 46
47. プロンプト：記事の作成（つづき） 【記事構成のガイドライン】 - 添付ファイルの順番に従って作成 - 作成する記事は、インタビュー相手の考えをまとめたコラムとして出力 - セクションごとに出力すること - 全体の文字数：4000文字程度 【出力形式】 - Markdown形式で出力 - 各セクションは必ず見出し（##）をつける - 読みやすい段落に整形 47
48. プロンプトの作成もAIに任せる ➢ 優れたIT系メディアの編集者の視点で、 技術記事をチェックするためのプロンプトを作成して 最初からAIに任せすぎると、 ブラックボックスになって自分で治せない。 まずは、手順ごとにAIを適用。 慣れてきたら任せる範囲を広げて、 4つの手順に沿って出力を確認する 48
49. まとめ 分かりやすい文章を書くための構造と手順 ◼ ドキュメントの４つの構造を意識しよう （企画 > アウトライン > 段落 > 文） ◼ この構造に沿って、順番に進めよう ◼ AI活用も手順に合わせて一歩づつ 49
50. ご清聴ありがとうございました ◼ Zenn： 俺のドキュメントライティング：分かりやすい文章を書く手順 https://zenn.dev/catch/articles/my_document_writting 50