Forkwell Press | フォークウェルプレス

SHARE

目次

目次

SHARE

キャリアとスキルアップ

「エンジニアのためのドキュメントライティング」 岩瀬 義昌

エンジニアのためのドキュメントライティング_アイキャッチ画像

\ ドキュメント作成はプロダクト開発と同じ…?! /

ITエンジニアなら誰しもが経験する
「ドキュメントを書いておけば良かった……」という経験。

そこで今回は、ドキュメントの書き方を体系的に学ぶイベントを開催しました。

このイベントレポートでわかること
■ドキュメントライティングのスキルが高まる
■ドキュメントの準備・作成・運用の重要なポイントを理解できる

アーカイブ動画はこちら

アーカイブでは視聴者からのQ&Aを見ることができます

  • ドキュメント文化を浸透させる方法
  • おすすめのドキュメント管理ツール
  • ドキュメントがない状態での引き継ぎ
  • 運用しやすいドキュメント構造とは
  • 増えすぎたドキュメントの管理方法
  • ドキュメントを残さないシニアエンジニアへの対策
  • ドキュメントへの苦手意識を克服する方法
  • 誰もドキュメントを読んでくれません
  • 複数人でドキュメント管理するコツ

本記事のTopics

  • 書籍の概要・構成
  • おすすめの書籍
  • 読み手の理解
  • ドラフトの執筆
  • フィードバックの収集と組み込み
  • ドキュメントの品質測定
  • 日本語を学べる書籍
書籍画像「ドキュメントライティング」
ドキュメントは開発側の生産性とユーザーの利便性を高めるもの。ドキュメントがなければ、ユーザーに使われる機会が確実に減ります。開発者がいかにすばらしいプロダクトを作ろうが、ドキュメントの欠如がその価値を奪うのです。

本書は、経験に長けた執筆者たちがドキュメントを作成する方法をゼロから説明するフィールドガイドです。

これまで学ぶ機会のなかったREADME、APIリファレンス、チュートリアル、コンセプトドキュメント、リリースノートなど、さまざまな種類のドキュメントの書き方について学ぶことができる一冊。

ドキュメントを作成している現場のエンジニアやテクニカルライター、プロダクトマネジャーの方に最適の内容です。

今までのエンジニア人生で最高のドキュメントは?

書籍の概要・構成

書籍『エンジニアのためのドキュメントライティング』は 3 PART で構成されます、本レポートはその中から下記の赤字部分のみを抜粋し紹介します。

PART I ドキュメント作成の準備
CHAPTER 1 読み手の理解
CHAPTER 2 ドキュメントの計画

PARTⅡ ドキュメントの作成
CHAPTER 3 ドキュメントのドラフト
CHAPTER 4 ドキュメントの編集
CHAPTER 5 サンプルコードの組み込み
CHAPTER 6 ビジュアルコンテンツの追加

PARTⅢ ドキュメントの公開と運用
CHAPTER 7 ドキュメントの公開
CHAPTER 8 フィードバックの収集と組み込み
CHAPTER 9 ドキュメントの品質測定
CHAPTER 10 ドキュメントの構成
CHAPTER 11 ドキュメントの保守と非推奨化

ドキュメント作成はプロダクト開発と同じ!

構成を見て気が付く方もいるかも知れませんが、ドキュメント作成のフローは、実はプロダクト開発と同じ流れ。新しく仮説を立て、実装・検証し、フィードバックをもらい、また最初に戻り…のサイクルです。

エンジニアのためのドキュメントライティングの登壇資料1

読み手の理解

「CHAPTER 1 読み手の理解」は、最も重要なポイントです。

ユーザーの理解を外すと、無価値なドキュメントが爆誕します。無価値なうえにメンテナンスコストがかかる最悪の状況が起こり続けるので、注意しましょう。ユーザーはドキュメントを読みたいのではなく、課題やニーズを解決したいのです。このことをまず頭に入れましょう。

ドキュメントを書く上で最も大事なこと

  •  読み手となるユーザーを理解すること
  • ユーザーは誰なのか?
  • ユーザーは何を達成したいのか?
  • ドキュメントで、どんな課題を解きたいのか?

どうすればユーザーを理解できるか

プロダクト開発をしているということは、必ず社内に議論の痕跡(図左)があるはずです。この痕跡を掘り起こすと、ユーザーが浮かび上がるので(仮説)次はその仮説を検証します(ユーザー理解の検証)。

  1. 議論の痕跡を探す
  2. ユーザーは誰か(という仮説)
  3. ユーザー理解(の検証)
エンジニアのためのドキュメントライティングの登壇資料2

最も効率的なのは、ユーザーとの対話

ユーザー理解のためには、ユーザーと直接対話することがベストです。下記のような方法を用いて対話を試みましょう。

  • 既存チャネルの活用
  • サポートチケット
  • インタビュー
  • アンケート

とくに「ここが使いにくくて困った!」という “怒りの気持ち” で書いたサポートチケットは、ユーザーの生の声。ぜひ活用を。

対話したら知見をまとめよう

インタビューメモは情報量が多いので頭の中にインプットしておくことは、ほぼ不可能。ユーザーの声を検証しつつ、まとめる作業もお忘れなく。

  • ユーザーペルソナ
  • ユーザーストーリー
  • ユーザージャーニーマップ

叩き台づくりにChatGPTを活用するのもアリ!

エンジニアのためのドキュメントライティングの登壇資料3

*ChatGPTを使用して作成したフリクションログの例

知識の呪い(認知バイアス)に、気を付けろ!

こんな経験はありませんか?

  • 同僚が耳慣れない専門用語で話している
  • 同僚が開発環境を作る手順を教えてくれない
  • デバッグでエラーメッセージを教えてくれたが、他に必要な背景情報は伝えてくれない

恐らく同僚に悪気はなく、知っていると思っていて伝えていない可能性があります。これが知識の呪い(認知バイアスの1つ)です。

呪いを断ち切る2つの方法

王道の方法は「ユーザーへの共感」を徹底することです。次に効果的な方法は、フリクションログを作ることです。フリクションは直訳すると「摩擦」や「抵抗」を意味しますが、プロダクト開発においては、プロダクトを使う際に「うまく使えないな」と感じたことや違和感を指します。自らプロダクトを使ってみて、この違和感をログで残しておくことが大切です。 

エンジニアのためのドキュメントライティングの登壇資料4

*ChatGPTを使用して作成したフリクションログの例

ドラフトの執筆

ドキュメントを書くうえで最も難しいことは、ゼロから書き始めるところです。つまり効率的に作成を進めるためには白紙からの脱却がキーワードになります。

分からなくてもいいので、手を動かそう

手を進めるコツ

  • 使い慣れたツールを使用する
  • ドキュメント作成のために、新たに何かを学ぶ必要はない
  • 紙・ペン・ホワイトボードなどなんでもOK

なんでもいいので、まず手を動かしましょう。書き始めてしまえばこっちのものです。

まずは、ユーザーと目的を整理する

  • 冒頭で整理すること
    • 誰が・何のために・読みにくるのか?
    • 「どのタイプ」のドキュメントが適切か?
  • 次にタイトルとアウトラインを決める
    • タイトル = ドキュメントを読んで達成できるゴールの要約
    • 例:カスタム会話型チャットボットの開発など
  • アウトライン=ゴールに必要な大まかな要素や手順
    • 例:開発環境、 API認証の方法など

肉付けしていく

ユーザーの目的を整理したら次は中身を書いていきましょう。中身に使用する要素はこのあたりです。

  • 見出し
    • ドキュメント内の道しるべ。ユーザーにとって、最も重要な情報を一番上に持ってくる
  • 段落
    • ドキュメントの詳細を理解できる
    • 情報量が多く、読むのが大変
  • リスト
    • さっと読みやすい
    • 重要度やアルファベット順にソートすると◯
  • コールアウト
    • あまり馴染みがないかも知れないが結構重要
    • システムの注意喚起
エンジニアのためのドキュメントライティングの登壇資料5

ユーザーはちゃんと読まない

自分自身の行動を思い返してみてください。何かに困っているとはいえ、隅々までドキュメントを読むでしょうか。タイトルや見出しから何となく読んでいくはずです。これをFパターンといいます。

つまり、ユーザーが必要な情報をすばやく見つけられる構造にしておくことがベストなのです。(流し読みしやすい構成にする)

エンジニアのためのドキュメントライティングの登壇資料6

最も重要な情報は冒頭で述べよ

もし手順書であれば、読了時点で達成できることを冒頭に書いておくと良いでしょう。

エンジニアのためのドキュメントライティングの登壇資料7

長い文章は分割し、読みやすくせよ

長文や長い段落は流し読みに向きません。見出し・リスト・サンプルコード・図表などを効果的に使用しましょう。

エンジニアのためのドキュメントライティングの登壇資料8

エンジニアは、まずサンプルコードを探す傾向が強い

エンジニア特有の事例ですが、動画や図よりも、まずサンプルコードを探す傾向が強いというデータがあります。サンプルコードについては本書 第5章で解説しているので、興味のある方はぜひご覧ください。

フィードバックの収集

ドキュメントはプロダクト機能の一部です。プロダクト同様にドキュメントそのものも仮説検証の対象になります。フィードバックを収集するフローは下記を参考にしてみてください。

  • ユーザーがフィードバックを送信する経路を用意
  • フィードバックを整理する
    • 有効なFBか? 優先度をトリアージする
エンジニアのためのドキュメントライティングの登壇資料9

ドキュメントの品質測定

エンジニアにはお馴染みの言葉「計測できないものは改善できない」。ドキュメントの計測は、どのように実施すべきでしょうか。

エンジニアのためのドキュメントライティングの登壇資料10

優れたドキュメントとはなにか、答えられるか?

計測にあたってまずは良いドキュメントの定義を知りましょう。目的にかなっているドキュメントが、優れたドキュメントです。

目的

  • ユーザーの特定の行動を促進する
  • 組織のゴールを達成する

優れたドキュメント、どちらが重要?

品質の計測は、機能品質・構造品質の2つに分けて考えることができます。さて、どちらの要素が重要でしょうか。

機能品質

  • ドキュメントの目的やゴールが達成されているか?
  • アクセシビリティがあること
  • 目的があること
  • 見つけやすいこと
  • 正確なこと
  • 完全であること

構造品質

  • ドキュメント自体がうまく書かれているか?
  • うまく構成されているか?
  • 構造品質(C)
    • Clear (L)
    • Concise (¥)
    • Consistent (LTC13)

答えは、圧倒的に機能品質です。どれだけ美しく整理された構造であっても「目的」を果たさないドキュメントが優れているとはいえません。

計測できる要素は無限大、取捨選択を

Web計測ツールを使用すれば、PV・UU・直帰率など、あらゆるメトリクスの計測ができます。重要なのは何を計測するかではなく、なぜ計測するのかです。

  • メトリクス活用の計画
    • なぜ計測したいのか
    • 計測した情報を何に活用するのか
    • その努力で、組織の目的・ゴールに近づけるのか
  • 基準値を確立する
    • 計測(集める)だけでは意味がない
    • 基準値を決めてビフォーアフターを知ることが大切

日本語を学ぶ!おすすめの書籍

日本語特有のルールや人に伝わる文章術を学ぶなら、下記の書籍がおすすめです。

書籍画像「理科系の作文技術」
書籍画像「日本語の作文技術」
書籍画像「日本語スタイルガイド」
書籍画像「ヘルプサイトの作り方」

登壇資料はこちら

ForlkwellPress ロゴ画像

フォークウェルプレス編集部

Follow

記事一覧へ

本サイト掲載の全て記事は、フォークウェル編集部が監修しています。編集部では、企画・執筆・編集・入稿の全工程をチェックしています。

岩瀬 義昌
岩瀬 義昌
NTTコミュニケーションズ

開発チーム

Docs for Developers 翻訳者。東京大学大学院修士課程修了後、 2009 年 NTT 東日本に入社し大規模 IP 電話システムの開発などに従事。 2014 年に内製、アジャイル開発に携わりたいという思いから、 NTTコミュニケーションズ SkyWay 開発チームに転籍。 以降、カンファレンスでの登壇、記事執筆、技術・組織・マネジメントなどを深掘りするポッドキャスト fukabori.fm の配信など様々なアウトプットがソフトウェアエンジニアの界隈で人気を呼ぶ。 2020 年よりヒューマンリソース部に異動し、人材開発や組織開発に従事し、 2022 年より全社のアジャイル開発・プロダクトマネジメントを支援している。