Docs for Developers の読書レポート

Slide 1

Slide 1 text

ディベロッパーのための  ドキュメント  エンジニア分野における  テクニカルライティングガイド  @kamimi 

Slide 2

Slide 2 text

Understanding your audience   聴衆を理解する    Planning your documentation   ドキュメントの計画をする    Drafting documentation   ドキュメントの下書きを作成する    Editing documentation   ドキュメントを編集する    Integrating code samples   コードサンプルを統合する  目次  Adding visual content   ビジュアルコンテンツを追加する    Publishing documentation   ドキュメントを公開する    Gathering and integrating feedback   フィードバックを集めて取り入れる    Measuring documentation quality   ドキュメントの質を測る    Organizing documentation   ドキュメントの整理    Maintaining and deprecating documentation   ドキュメントのメンテナンスと廃止  1  2  3  4  5  6  7  8  9  10  11 

Slide 3

Slide 3 text

　　 Understanding your audience  　　聴衆を理解する 1 

Slide 4

Slide 4 text

  知識の呪い（The curse of knowledge）  「人は他人が同じ知識を持っていると思う傾向にある」 

Slide 5

Slide 5 text

ユーザへの共感が必要  - ユーザリサーチを行い、ユーザーが必要とする前にそのニーズを予測する  ユーザは誰か、目的は何か、ニーズは何かを調査、検討する  - ペルソナ  - ユーザーストーリー  - ジャーニーマップ 

Slide 6

Slide 6 text

Planning your documentation   ドキュメントの計画をする  2 

Slide 7

Slide 7 text

ユーザニーズを元に、ドキュメントの計画を立てる  - コンテンツタイプ  - コンテンツタイプに適したパターン  - 特定コンテンツの組み合わせ  - コンテンツを作成するための包括的な計画 

Slide 8

Slide 8 text

コンテンツタイプ  - コードコメント  - README  - Getting started documentation  - Conceptual documentation  - Procedural documentation  - Reference documentation  - API reference  - Glossary  - Troubleshooting documentation  - Change documentation  ドキュメント計画のアウトラインを決める 

Slide 9

Slide 9 text

Drafting documentation   ドキュメントの下書きを作成する  3 

Slide 10

Slide 10 text

  書くことに関して最も難しいことの1つは、  空の文書に立ち向かうこと 

Slide 11

Slide 11 text

- ライティングツールの選択  - 文書の対象ユーザと目標を定義  - アウトラインの作成  - 段落、リスト、吹き出しを使ってコンテンツを作成  - 執筆中に行き詰まらないようにする 

Slide 12

Slide 12 text

- 2つの真実  - 読者は情報を求めて文章を見る  - 読者はあなたが書いたものをほとんど読んでいない    - 書くのに詰まる  - 詰まる理由が特定できれば、解決するのは簡単になる  - テンプレから取り掛かる 

Slide 13

Slide 13 text

Editing documentation   ドキュメントを編集する  4 

Slide 14

Slide 14 text

  編集は、ドキュメントを確認して、  ユーザのニーズを満たしていることを確認するプロセス   

Slide 15

Slide 15 text

  - 編集へのさまざまなアプローチを理解する  - 優れたドキュメントには色々と側面があるが、一気に全部に焦点を当てようとするのではなく、１つずつ考えていこう  - 標準化された編集プロセスを作成する  - 自分でドキュメントをレビュー→レビューを依頼する→テクニカルレビューを依頼する  - フィードバックの受け入れと統合 

Slide 16

Slide 16 text

Integrating code samples   コードサンプルを統合する  5 

Slide 17

Slide 17 text

  コードサンプルは、効果的な開発者ドキュメントの  重要な部分。  テキストよりコードサンプルの方が多くを語る 

Slide 18

Slide 18 text

- コードサンプルのタイプ  - 実行可能と説明（実行可能ではないが読者が学んだり比較する出力やコードブロック）の2種類がある  - 良いコードサンプルの原則  - 説明的、正確、明瞭、役に立つ（拡張可能）、信頼できる  - 役に立つコードサンプルを設計する  - 言語を選ぶ、さまざまな複雑さにフォーカスを当てる、コードをプレゼンテーションする  - ソースコードからサンプルを生成する   

Slide 19

Slide 19 text

Adding visual content  ビジュアルコンテンツを追加する  6 

Slide 20

Slide 20 text

  1枚の絵は千の言葉に値する 

Slide 21

Slide 21 text

- ビジュアルコンテンツを作るのは難しい - ビジュアルコンテンツは補足であり、文書に代わるものではない - 理解力（これは読者を助けるか？）、アクセシビリティ（読者を除外しているか）、パフォーマンス（コンテンツのサイズや形式は読者を助けるかそれとも妨害するか）

Slide 22

Slide 22 text

- スクショを使う  - よくある図  - ボックスと矢印、フローチャート、スイムレーン図  - 図を書くこと  - 単純化  - 図ごとに1つのアイディア    - ビデオコンテンツの作成  - ビデオは新しいコンテンツを導入する時には役に立つが、作成が困難でメンテにコストがかかるので、よく検討して導入すべき 

Slide 23

Slide 23 text

Publishing documentation   ドキュメントを公開する  7 

Slide 24

Slide 24 text

公開するとは、コンテンツを意図したユーザが  電子的に利用できるようにすること  コードと同じで完璧なものはないので、フィードバックに基づいて繰り返し処理することが必要   

Slide 25

Slide 25 text

- コンテンツのリリースプロセスの構築  - いつどこでどうやって公開するのか  - 公開までのタイムラインの作成  - プロダクトのリリーススケジュールとドキュメントの公開スケジュールを調整  - 公開の確定と承認  - 読者へコンテンツをアナウンス  - 利用可能な新しいリソースがあることを人々に知らせることがだいじ  - 将来のための計画  - ドキュメントの更新頻度、何を更新するか、リリースプロセスの改善   

Slide 26

Slide 26 text

Gathering and integrating feedback   フィードバックを集めて取り入れる  8 

Slide 27

Slide 27 text

  ユーザからのフィードバックの収集は、  製品とドキュメントがどこで成功し、  どこで改善すべきかを知るのに役立つ 

Slide 28

Slide 28 text

- ユーザフィードバック用のチャンネルを作成する  - フィードバックをアクションに変える    - 受け取ったフィードバックに優先順位をつける    - ユーザのフォローアップも大事  - 直接連絡して感謝を示したり   

Slide 29

Slide 29 text

Measuring documentation quality   ドキュメントの質を測る  9 

Slide 30

Slide 30 text

ドキュメントの質を理解する  - 「ドキュメントは目的を果たすといいものになる」  - 機能品質：ドキュメントが目的を達成しているかどうか  - 特に機能品質が大事  - 構造品質：ドキュメントが適切に記述され、構造化されているか 

Slide 31

Slide 31 text

- ドキュメントの分析戦略を立てる  - ドキュメントの目標が読者や組織の大きな目標とどのように一致しているか、を認識するのに役立つ    - メトリクスのクラスターの使用  - メトリクス間の関係を関係づけることでより良い示唆が得られる   

Slide 32

Slide 32 text

Organizing documentation   ドキュメントの整理  10 

Slide 33

Slide 33 text

  ドキュメントの整理とは、  既存のコンテンツを評価し、  情報アーキテクチャを計画・構築し、  新しい組織スキームにコンテンツを移行すること 

Slide 34

Slide 34 text

- 情報アーキテクチャの設計  - 情報アーキテクチャとは、ドキュメントに適用する組織構造。読者が適切なコンテンツを見つけられるようにする  - 一貫性、関連性、検索可能    - 情報アーキテクチャの実装  - 情報アーキテクチャの文書化も大事  - プロダクトとドキュメントが進化するに従い、ユーザのメンタルモデルの検証も行うべき   

Slide 35

Slide 35 text

Maintaining and deprecating documentation   ドキュメントのメンテナンスと廃止  11 

Slide 36

Slide 36 text

  ドキュメントの内容とコードの動作のギャップ  が大きければ大きいほど、  プロダクトへの信頼度が低くなる 

Slide 37

Slide 37 text

- メンテナンスの計画  - 新機能を追加するときはコードとコンテンツの両方にどのような変更を行う必要があるかを検討すべき    - 役に立つメンテナンスツール  - メンテナンスを自動化する  - 最終更新日表示しリマインダーを送るなどして陳腐化を防ぐ  - リンク有効チェック  - Linterでのチェック  - ドキュメントの自動生成（OpenAPIなど） 

Slide 38

Slide 38 text

- 不要なコンテンツを廃止したり除去する  - 削除するときは単に削除するのではなく、非推奨または削除されることがユーザにわかるように  - 移行ガイドがあるとベスト  - ドキュメントはユーザにとって役に立たなくなったら削除すべき