やったこと 書籍「エンジニアのためのドキュメントライティング」 PART1 (1章、2章) 読了 学んだこと 1章 読み手の理解 ドキュメントは、読み手のためのもの。 まずは、読み手のことを知る必要がある。 「知識の呪い」は、読み手の理解を妨げる。 ❓知識の呪い 「自分が知っていることは、相手も知っている」と思い込むこと。 いくつかのステップを踏むことで、知識の呪いから逃れ、ユーザーを理解することができる。 ユーザーのゴールを特定する 「ドキュメントを読んで、ユーザーが達成したいこと」を突き止め、ゴールとして定める 注意点として、プロダクトのゴールと、ユーザーのゴールは、必ずしも一致しない ユーザーを理解する どんなユーザー（開発者・マネジャーといったロール、技術習熟度など）がドキュメントを読むのか、想定する ユーザー全員のニーズを満たすことは不可能 ビジネスやプロダクトにとって最も重要なユーザーを優先すること 例？）セキュリティ、SRE、開発では、いずれも求められる情報が異なるはず ユーザーのニーズを理解し、ドキュメントがそれをどう解決するか理解する 詳細は後述 わかったことを、ツール（ペルソナ、ストーリー、マップなど）を使ってまとめる フリクションログを使って仮説検証する ユーザーの立場に立って、ユーザーの目的達成を阻害する要因（≒フリクション）を自分で体験する よくあるユースケースを定義し、自分でなぞらえると良い ❓フリクション（ログ） 摩擦や抵抗のこと。 特に、ソフトウェアやサービスをうまく使えなかったことや違和感といった体験を示す。 "フリクションログ" だと、摩擦や抵抗を示す記録。 ユーザーのニーズを理解し、ドキュメントがそれをどう解決するか理解する ドキュメントで答える必要がある（≒ユーザーが疑問に思う事項）のリストを作る。 よくある疑問は、以下の通り。 これは何のプロダクト？ 個のプロダクトが解決する問題は？ どんな機能がある？ 費用はどれぐらいかかる？ どこから始められる？ 出来上がったリストを、「アウトラインの作成」という形でまとめる。 アウトラインが出来上がり次第、「ユーザーは誰か」「ユーザーのゴール」「ユーザーのニーズ（アウトライン）」を検証する。 検証の際は、ユーザーのウォンツ（要望）ではなく、のニーズ（要求）に焦点を当てること。 主な検証方法は以下の通り。 サポートチケットなど、存時の情報リソースを使う インタビュー、アンケートなどで、新しいデータを集める 2章 ドキュメントの計画 ユーザーのニーズに合わせて、コンテンツの種類（手順書、クイックスタートなど）を決定していく。 よく使われるコンテンツタイプは以下の通り。 コードコメント README スタートガイド コンセプトドキュメント 手順書 チュートリアル ハウツーガイド リファレンスガイド トラブルシューティングドキュメント 変更に関するドキュメント リリースノート 質の高いドキュメントを作成するために、ドキュメント作成の計画を立てる。 以下の質問に答えることで、ユーザーにとって適切な情報を絞り込むことが出来る。 対象の読み手は誰か？ プロダクトのローンチから、ユーザーに一番学んでもらいたいことは何か？ 重要度順で考えると、どの機能からリリースされていくか？ ユーザーはローンチに何を期待しているか？ ユーザーがプロダクトや機能を使い始める前に必要な事前知識はあるか？ 何のユースケースをサポートしているか？ ユーザーが躓きそうな既知の課題や、フリクションはあるか？ これらの質問に答えることで、コンテキストを形成できる。 コンテキストが分かってくると、何から作り始めればよいか決められるようになる。 コンテンツのアウトライン作成から、ドキュメント計画を立てると良い。 以下、コンテンツアウトラインの例 タイトル コンテンツのタイプ 簡単な説明 xxx スタートガイド スタートガイド xxxを使うための非常に簡単なデモと他のドキュメントへのリンク xxx yyy機能の解説 コンセプト yyy機能の仕組みの技術説明 認証方法 ハウツーガイド 認証スルタンのステップバイステップ手順 APIリファレンス APIリファレンス API呼び出し方法と構文の一覧 リリースノート l変更履歴 xxxのリリースノート 以下、コンテンツタイプ別の追加情報。 コードコメント コーディング上の意思決定とその背景や、トレードオフを記録することで、読み手である将来の開発者の時間を節約する 過剰なコメントは、保守コストが増大することを念頭に置くこと README 以下の役割を担う 読み手に、システム全体の概要を理解してもらう リポジトリに対するチートシートとして機能する ユーザーが利用する包括的なドキュメントの基礎（ポータル）として機能する より詳細な情報が必要な場合は、重要なサブフォルダに追加情報を配置し、追加情報へのリンクをREADMEに貼る テンプレート スタートガイド 読み手（ユーザー）の立ち上げを支援する より高度（≒専門的・詳細）なコンテンツへ進む前のスタート地点として機能する スタートガイドを書く上で、自身に問うべき質問は以下の通り サービス内容と核となる機能を一番短く説明するなら？ プロダクトをインストールして使うための最も簡単な方法は？ 新規ユーザーが感じる最も重要な疑問は？ サービスを使ってできるすごい事は何か？ コンセプトドキュメント サービスの裏側にある考え方とアイデアの理解を助ける 手順書やチュートリアルの背景を説明する ... といった用途で作成する 実装に関する詳細は、コンセプトドキュメントの領分ではない（手順書などの領分） テンプレート 手順書 具体的には、「チュートリアル」と「ハウツーガイド」が該当する 読み手（開発者）が、特定のゴールを達成する方法を、手順として説明する 以下、手順書作成時のガイド できるだけガイド単体で読めるようにする ユーザーが必要とするすべての行動を1つのページにまとめる 手順数を最低限に絞る ステップが多いほど、読み手は複雑に感じ、ミスが多発する ステップが多いほど、手順書の保守が大変になる 長文説明を避ける 説明が長すぎると感じたら、コンセプトガイド等に分割すること チュートリアル 手順書に分類されるドキュメント 読み手に、特定のゴールを達成する方法（≒手順）を伝える（≒学習させる）ことを目的とする 長く、時間のかかるチュートリアルを、ユーザーがやり遂げる可能性は低い 長すぎる手順は、サービスが複雑すぎる可能性を示唆する ハウツーガイド 手順書に分類されるドキュメント 現実のビジネス課題を解決するための、特定の手順を説明する チュートリアルのような学習目的ではなく、実装に基づく課題解決が目的 以下、良いハウツーガイドの特徴 シンプルな言葉を使用する 行動を明確にする ハイツーガイドが解決する問題を継続的に改善する ガイドの冒頭には、前提条件を入れると良い リファレンスガイド 行動とその結果を説明する APIリファレンス、用語集、トラブルシューティングドキュメントなどが該当する トラブルシューティングドキュメント リファレンスガイドに分類されるドキュメント 既知の問題に対して、その回避策、または解決策を説明する 説明よりも、回避策に集中すること 読み手の大部分は、「なぜ問題が発生したか」ではなく、「どうやったら問題を回避、または解決できるか」に関心を持つため エラーメッセージとその説明、および解決策を列挙するのも手 テンプレート 変更に関するドキュメント リファレンスガイドに分類されるドキュメント 変更時期、顧客に影響が出たタイミングなどを整理し、トラブルシューティングに役立てる 以下の情報を記録する 過去のサポートバージョン、統合、または廃止予定の機能 パラメータや重要なフィールドの名前の変更 オブジェクトやリソースの移動 リリースノート リファレンスガイドに分類されるドキュメント（特に、変更に関するドキュメントの一種） 変更履歴の背景情報を記載し、読み手に対して、ある変更が生じた理由を説明する リリースノートには、以下の内容を記載する 新機能 バグ修正 既知のバグや制約 移行方法 テンプレート

やったこと 書籍「エンジニアのためのドキュメントライティング」 PART2 (3,4,5,6章) 読了 学んだこと 3 章 ドキュメントのドラフト 白紙のドキュメントの冒頭に、「読み手、目的、コンテンツパターン」を書くところからスタート。 タイトルを決める 「読み手、目的、コンテンツパターン」が決まると、タイトルを決定できる（特に「目的」は有用）。 タイトルを見た瞬間、ゴールがイメージできるようなフレーズにする そのため、キュメントのゴールは一つに絞ること 複数のゴールが存在する場合、ゴールが一つになるようドキュメントを分割すること アウトラインを作る 読み手が、タイトルに書いたゴールを達成するために、読み手が知っておくべきこと、やるべきことを考え、必要な手順を列挙する。 ゴールを達成するために、ゴールをサブタスクに分割するイメージ 正しいタイミングで、正しい情報を読み手に提供できるよう、アウトラインを修正する。 順序を変える （必要に応じて）項目を追加・削除・変更する 複雑すぎる場合、項目を分割する 以下の質問を自身に投げかけ、アウトラインをレビューする。 追記すべき事前情報や設定情報はあるか？ 飛ばしている手順や、説明が不完全な手順は無いか？ 手順は合理的な順で並んでいるか？ アウトラインに自信が持てたら、アウトラインの項目を肉付けしてく。 流し読みに対応する 大多数の読み手は、必要な情報を求めてドキュメントを流し読みする（F 型）。 流し読みする読み手を想定し、必要な情報を見つけやすくすることは重要。 流し読みする読み手に役立つコンテンツ作りの戦略は、以下の通り。 最も重要な情報を冒頭で述べる ドキュメントのゴールを要約して、タイトルに設定する 大きな文章の塊を分割する 複数の長文ドキュメントを分割する 簡潔さと明確さに向けて努力する 「このコンテンツで読み手のニーズを満たせているか？」と問い、改善に努める ドラフト作成に行き詰ったら 完全主義からの脱却 かけるところから書く 周りの人に、助けを求める 足りないコンテンツを強調する 書けない（重要な情報が欠けているなど）箇所は、TODO, T.B.D. などと書いていったんスルー 確信をもって書ける部分から書いていく 順不同で書く 書けるところから書く メディア（ツールや手法など）を変える ドラフトを完成させる 以下、ドラフト完成のチェックリスト。 [ ] 大見出しはドキュメントのゴールを要約しているか？ [ ] 複数の見出しによってドキュメントは十分に要約されているか？ [ ] ドラフトは最初から最後まで読み手のニーズにこたえているか？ [ ] 情報の流れは読み手に取って理解しやすいものか？ [ ] 何らかのドキュメントパターンやテンプレートに正しく従っているか？ [ ] 全手順が動作することをテストし確かめたか？ 4 章 ドキュメントの編集 ここで言う編集とは、ドキュメントを見て、ユーザーニーズに応えているか確認するプロセス。 レビューや評価といった、分析的なプロセスではない。 編集方法 編集プロセスを一連の複数の周回に分解して、一つの周回で一つの観点に絞って編集すると良い。 編集速度が向上する 開発者向けドキュメントだと、以下の観点で編集を周回すると良い。 技術的な正確さ 観点 指示通りに作業すれば、ドキュメントに記載された結果が得られるか？ 技術的な専門用語、もしくは混乱しやすい用語はあるか？ コードの関数、パラメータ、エンドポイントは正しく命名され、説明されているか？ 手順があれば、指示通り実行して、うまくいくことを確認すること 手順に制約条件があれば明記する事 完全性 観点 TODO, T.B.D. が無いこと コンテンツにギャップが無いか OS 上の制約や情報の有効期限があれば記載する 構成 観点 タイトルと見出しから、何について書かれたドキュメントか明確になっているか？ ドキュメントは、一貫性のある、論理的な方法で構成されているか？ 他のドキュメントに配置すべきセクションは無いか？ テンプレートが存在するならば、テンプレートに従って書かれているか？ 一貫した構成は、予測が可能となり、読み手が適切な部分にたどり着きやすくなる 読み手がコンテンツを読む前後にすべきことが無いか確認する 読み手は、前後のドキュメントを読まず、いきなり特定の章から読み始めることが少なくないため 明確さと簡潔さ 不自然な表現は書き換え、重複情報を削除し、不要な言葉を取り除く コンテンツはできる限り短くし、要点を絞る さしずめ、ドキュメントに対するリファクタリング ドキュメントレビュー 自身でレビューする場合、以下のチェックリストを使用する。 [ ] タイトルが短くて具体的である [ ] 見出しは論理的に並べられており、一貫性がある [ ] ドキュメントの目的が最初の段落で説明されている [ ] 手順はテストされていて動作する [ ] 技術的なコンセプトが説明されている、もしくはリンクされている [ ] テンプレートの構成に従っている [ ] リンクがすべて有効である [ ] 誤字脱字・文法チェックツールが実行されている [ ] グラフィックや画像が明確で有用である [ ] 前提条件や次のステップが定義されている 他のメンバーにレビューを依頼する場合、レビューの観点を伝えること。 構成をレビューしてほしいのか？技術面なのか？明確さと簡潔さを見てほしいのか？ など また、フィードバックの受け取り方も合意しておくこと。 場合によっては、専門家にレビューを依頼する（=>テクニカルレビュー） もらったフィードバックを取り入れる ドキュメントのゴールは、知識を読み手に効果的に伝えること。 フィードバックは、非難ではなく、より効果的に伝える方法を指摘するものだと捉える。 矛盾したフィードバックがある場合、「ユーザーがこのドキュメントを読んで達成したいこと」、つまりはゴールを満たすことに繋がるフィードバックを優先する。 どのみち、全てのフィードバックに対応するのはリソース的にも困難となりやすい 良いフィードバックを提供するためには、以下を守る。 フィードバックの際は、「人」ではなく、「アイデア」に集中する 「あなたが間違っている」ではなく、「この部分が不明確だ」といった具合 批判に続けて、建設的な代替案を出す フィードバックに反応するための時間を確保する また、フィードバックでは素晴らしかった部分を伝えてもよい。 素晴らしい文章を共有することで、他の人がまねできるようになる。 5 章 サンプルコードの組み込み 良いサンプルコードは、文章で説明する以上に多くの情報を読み手に提供できる。 サンプルコードは、一般的に「説明用」と「実行可能なもの」の二種類存在する。 実行可能なサンプルコードは、コピペ（かつ必要に応じて改変）して実行できるコード 説明用のサンプルコードは、読み手の理解向上や、読み手の環境での実行結果を比較する目的で使用するコード 良いサンプルコードの原則 読み手は、サンプルコードが（可能ならコピペしてそのまま）動作することを期待する。 そんな、良いサンプルコードは、以下の原則を満たすべき。 説明されていること サンプルコードのそばに、コードの必要性を説明したコメントが存在すること コードを動かすために必要な前提条件が、全て説明されていること 制約などがあれば、きちんと書くこと 簡潔であること 読み手が必要とする、過不足ない量の情報が提供されていること 明確であること 読み手が期待する言語習慣に従ってサンプルコードが書かれている 読み手が混乱しないよう、複雑なテクニックは避ける 加えて、実行可能なコードは、以下の原則を満たすべき。 利用可能（であり拡張可能）であること パラメータの置き換えが必要な場合、置換用データを説明する 何で置き換えればよいのか一目でわかる変数を使用すること your_password や replace_with_actual_xxx など 信頼できること ペースト可能であり、動作し、余計なことを実行しない サンプルコードの設計 サンプルコードの設計に当たっては、以下の点を留意する。 読み手になじみがあって、最も使われそうな言語を選んで、サンプルコードを作成する 快適さ・理解度合いに幅がある読み手をサポートするため、様々な複雑さのサンプルコードを提供する 初心者向けだと、 hello_world レベル 習熟した読み手向けだと、 特定のユースケースに特化したサンプルコードなど 入門者向けドキュメントと、熟練者向けドキュメントを混同しないよう注意すること コードだと一目でわかるような、一貫したスタイルでサンプルコードを提供する Markdown なら バッククォート がメジャー その他、サンプルコードに関する Tips 実行可能なコードは、動作確認しておくこと 場合によっては、読み手が自由にコードを試せるサンドボックスを提供する 多くのユースケースでは過剰な選択 サンプルコードを自動生成する 背景説明といった文脈が必要な場合、人手によるコメント追加も行うこと 6 章 ビジュアルコンテンツの追加 " 百聞は一見にしかず " 。 ビジュアルコンテンツはドキュメント補助が目的。 ドキュメントの代替にはなり得ない。 ビジュアルコンテンツの目的は、ドキュメントの理解促進であり、これに寄与しない情報は全て邪魔、ぐらいに思っておくこと。 読み手の必要とする情報と、作り手の好みは、異なることが多い ビジュアルコンテンツは、以下の三点を満たすことを常に意識する。 理解容易性 読み手に役立つ情報であること アクセシビリティ 読み手を限定しないこと パフォーマンス ビジュアルコンテンツの掲載によって、ドキュメント表示が遅くなり、読み手の時間を奪わないこと ビジュアルコンテンツも、ドキュメント同様にレビューすること。 その際、上記三点を満たしているかがレビューの観点となる。 ビジュアルコンテンツの例 スクリーンショット 可能なら、画像が表現している情報を、文章でも表現すると良い 加えて、画像が、さも存在しないようなコンテンツ説明文にすると良い ×「メニュー上部にある小さな歯車の画像」 〇「メニュー上部に小さな歯車があります」 コピペが必要になりそうな情報をスクショで提供しないこと 図表 ボックスと矢印 文書単体では説明が難しい、エンティティ間のデータの流れや関係性をわかりやすく描くことが出来る 使用する図形に一貫性を持たせること 必要なら凡例を記載すること フローチャート プロセスをドキュメントに落とし込むことが出来る 使用する図形に一貫性を持たせること スイムレーン 複数のコントリビューター（もしくはアクター）が存在する状況を表現できる 複数のコントリビューター（もしくはアクター）が存在することを除けば、特徴はフローチャートと同じ 図の目的は " 単純化 "。 一つの図で表現するアイデアは、一つに絞ること 場合によっては複数の図に分割すること 図表の要素には、可能なら、読み手の理解を促進するようなラベルを付与すること 色に一貫性を持たせること 基本は、ラベルで情報を伝える 可能なら SVG 形式で画像を公開すること 映像コンテンツには注意 映像コンテンツには、以下の問題点があり、総じて高コスト。 作成には専門知識が必要であり、素人には難しい 修正が困難（≒保守コストが非常に高い） 基本的には、上記問題点によるデメリットが大きい。 数枚の図で大体できないか検討すること。

やったこと 書籍「実践NextJS」1章 読了 学んだこと Route 系の用語整理 Tree/Subtree Tree ... 階層構造 Subtree ... 入れ子のTree Root ... TreeまたはSubtreeにおける根っこのノード Leaf ... 子を持たないノード Segment / Path example.com/profile/settings example.com ... ドメイン名 profile , settings ... Segment profile/settings ... Path 特定のPathに対応する Segment を、 「Root Segment」 と呼ぶ。 末端（≒子Segment を持たない）Segment を Leaf Segment と呼ぶ。 Dynamic Route / Dynamic Segment Pathが動的に変わり得るRouteを Dynamic Route と呼ぶ。 ID情報を含む場合など Dynamic Route を構成するSegment を Dynamic Segment と呼ぶ。 Route Segment の構成 app ディレクトリを頂点に、ファイル配置でRouteを表現する。 src/app/ ├── company-info │ └── page.tsx // localhost:3000/company-info ... └── page.tsx // localhost:3000/ (ルート) layout.tsx Header , Footer , サイドナビなど、全画面共通で表示したいUIを実装する場所。 また、layoutファイルはネスト出来る。 つまり、layoutファイルは、Segment毎に設けることが出来る。 Segment は Pageファイル必須ではなく、layoutファイルだけでも良い。 ナビゲーションの概念と用語 ハードナビゲーション ... 画面を再読み込みする画面遷移 ソフトナビゲーション ... 画面を再読み込みしない画面遷移 ※ナビゲーション ... 画面遷移のこと NextJS の SPAは「ソフトナビゲーション」。 加えて、データやレンダリングした画面をキャッシュしてくれる。 Dynamic Segment [categoryName] 部分が Dynamic Segment。 ディレクトリ構成 ├── categories │ └── [categoryName] │ └── page.tsx index.tsx ... <li> <Link href="/categories/flower">花</Link> </li> <li> <Link href="/categories/animal">動物</Link> </li> ... 所感 NextJS で言う Route は、ファイルシステムに近そう "Root Segment" の解説から、どのSegment も、必ずRootを持つ...ということになりそう layout ファイルを使いこなすことで、コードを共通化 が捗りそう dynamic segment は、機能としては理解できたが、有効なユースケースが思い浮かばない 経験を積めばわかるかな？