Docs for Developers の読書レポート

Transcript

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

2. 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

3. 　　 Understanding your audience
 　　聴衆を理解する 1

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

21. - ビジュアルコンテンツを作るのは難しい - ビジュアルコンテンツは補足であり、文書に代わるものではない - 理解力（これは読者を助けるか？）、アクセシビリティ（読者を除外しているか）、パフォーマンス（コ ンテンツのサイズや形式は読者を助けるかそれとも妨害するか）
22. - スクショを使う
 - よくある図
 - ボックスと矢印、フローチャート、スイムレーン図
 - 図を書くこと
 - 単純化
 - 図ごとに1つのアイディア
 
 - ビデオコンテンツの作成
 - ビデオは新しいコンテンツを導入する時には役に立つが、作成が困難でメンテ にコストがかかるので、よく検討して導入すべき

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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