Docs for Developers の読書レポート

Transcript

1. ディベロッパーのための

   ドキュメント

   エンジニア分野における

   テクニカルライティングガイド

   @kamimi

   

   View Slide

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

   

   View Slide

3. 　　 Understanding your audience

   　　聴衆を理解する
   1

   

   View Slide

4. 

   知識の呪い（The curse of knowledge）

   「人は他人が同じ知識を持っていると思う傾向にある」

   

   View Slide

5. ユーザへの共感が必要

   - ユーザリサーチを行い、ユーザーが必要とする前にそのニーズを予測する

   ユーザは誰か、目的は何か、ニーズは何かを調査、検討する

   - ペルソナ

   - ユーザーストーリー

   - ジャーニーマップ

   

   View Slide

6. Planning your documentation
   

   ドキュメントの計画をする

   2

   

   View Slide

7. ユーザニーズを元に、ドキュメントの計画を立てる

   - コンテンツタイプ

   - コンテンツタイプに適したパターン

   - 特定コンテンツの組み合わせ

   - コンテンツを作成するための包括的な計画

   

   View Slide

8. コンテンツタイプ

   - コードコメント

   - README

   - Getting started documentation

   - Conceptual documentation

   - Procedural documentation

   - Reference documentation

   - API reference

   - Glossary

   - Troubleshooting documentation

   - Change documentation

   ドキュメント計画のアウトラインを決める

   

   View Slide

9. Drafting documentation
   

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

   3

   

   View Slide

10. 

    書くことに関して最も難しいことの1つは、

    空の文書に立ち向かうこと

    

    View Slide

11. - ライティングツールの選択

    - 文書の対象ユーザと目標を定義

    - アウトラインの作成

    - 段落、リスト、吹き出しを使ってコンテンツを作成

    - 執筆中に行き詰まらないようにする

    

    View Slide

12. - 2つの真実

    - 読者は情報を求めて文章を見る

    - 読者はあなたが書いたものをほとんど読んでいない

    

    - 書くのに詰まる

    - 詰まる理由が特定できれば、解決するのは簡単になる

    - テンプレから取り掛かる

    

    View Slide

13. Editing documentation
    

    ドキュメントを編集する

    4

    

    View Slide

14. 

    編集は、ドキュメントを確認して、

    ユーザのニーズを満たしていることを確認するプロセス

    

    

    View Slide

15. 

    - 編集へのさまざまなアプローチを理解する

    - 優れたドキュメントには色々と側面があるが、一気に全部に焦点を当てようと
    するのではなく、１つずつ考えていこう

    - 標準化された編集プロセスを作成する

    - 自分でドキュメントをレビュー→レビューを依頼する→テクニカルレビューを依
    頼する

    - フィードバックの受け入れと統合

    

    View Slide

16. Integrating code samples
    

    コードサンプルを統合する

    5

    

    View Slide

17. 

    コードサンプルは、効果的な開発者ドキュメントの

    重要な部分。

    テキストよりコードサンプルの方が多くを語る

    

    View Slide

18. - コードサンプルのタイプ

    - 実行可能と説明（実行可能ではないが読者が学んだり比較する出力やコード
    ブロック）の2種類がある

    - 良いコードサンプルの原則

    - 説明的、正確、明瞭、役に立つ（拡張可能）、信頼できる

    - 役に立つコードサンプルを設計する

    - 言語を選ぶ、さまざまな複雑さにフォーカスを当てる、コードをプレゼンテーショ
    ンする

    - ソースコードからサンプルを生成する

    

    

    View Slide

19. Adding visual content

    ビジュアルコンテンツを追加する

    6

    

    View Slide

20. 

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

    

    View Slide

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

    View Slide

22. - スクショを使う

    - よくある図

    - ボックスと矢印、フローチャート、スイムレーン図

    - 図を書くこと

    - 単純化

    - 図ごとに1つのアイディア

    

    - ビデオコンテンツの作成

    - ビデオは新しいコンテンツを導入する時には役に立つが、作成が困難でメンテ
    にコストがかかるので、よく検討して導入すべき

    

    View Slide

23. Publishing documentation
    

    ドキュメントを公開する

    7

    

    View Slide

24. 公開するとは、コンテンツを意図したユーザが

    電子的に利用できるようにすること

    コードと同じで完璧なものはないので、フィードバックに基づいて
    繰り返し処理することが必要

    

    

    View Slide

25. - コンテンツのリリースプロセスの構築

    - いつどこでどうやって公開するのか

    - 公開までのタイムラインの作成

    - プロダクトのリリーススケジュールとドキュメントの公開スケジュールを調整

    - 公開の確定と承認

    - 読者へコンテンツをアナウンス

    - 利用可能な新しいリソースがあることを人々に知らせることがだいじ

    - 将来のための計画

    - ドキュメントの更新頻度、何を更新するか、リリースプロセスの改善

    

    

    View Slide

26. Gathering and integrating feedback
    

    フィードバックを集めて取り入れる

    8

    

    View Slide

27. 

    ユーザからのフィードバックの収集は、

    製品とドキュメントがどこで成功し、

    どこで改善すべきかを知るのに役立つ

    

    View Slide

28. - ユーザフィードバック用のチャンネルを作成する

    - フィードバックをアクションに変える

    

    - 受け取ったフィードバックに優先順位をつける

    

    - ユーザのフォローアップも大事

    - 直接連絡して感謝を示したり

    

    

    View Slide

29. Measuring documentation quality
    

    ドキュメントの質を測る

    9

    

    View Slide

30. ドキュメントの質を理解する

    - 「ドキュメントは目的を果たすといいものになる」

    - 機能品質：ドキュメントが目的を達成しているかどうか

    - 特に機能品質が大事

    - 構造品質：ドキュメントが適切に記述され、構造化されているか

    

    View Slide

31. - ドキュメントの分析戦略を立てる

    - ドキュメントの目標が読者や組織の大きな目標とどのように一致しているか、
    を認識するのに役立つ

    

    - メトリクスのクラスターの使用

    - メトリクス間の関係を関係づけることでより良い示唆が得られる

    

    

    View Slide

32. Organizing documentation
    

    ドキュメントの整理

    10

    

    View Slide

33. 

    ドキュメントの整理とは、

    既存のコンテンツを評価し、

    情報アーキテクチャを計画・構築し、

    新しい組織スキームにコンテンツを移行すること

    

    View Slide

34. - 情報アーキテクチャの設計

    - 情報アーキテクチャとは、ドキュメントに適用する組織構造。読者が適切なコン
    テンツを見つけられるようにする

    - 一貫性、関連性、検索可能

    

    - 情報アーキテクチャの実装

    - 情報アーキテクチャの文書化も大事

    - プロダクトとドキュメントが進化するに従い、ユーザのメンタルモデルの検証も
    行うべき

    

    

    View Slide

35. Maintaining and deprecating documentation
    

    ドキュメントのメンテナンスと廃止

    11

    

    View Slide

36. 

    ドキュメントの内容とコードの動作のギャップ

    が大きければ大きいほど、

    プロダクトへの信頼度が低くなる

    

    View Slide

37. - メンテナンスの計画

    - 新機能を追加するときはコードとコンテンツの両方にどのような変更を行う必
    要があるかを検討すべき

    

    - 役に立つメンテナンスツール

    - メンテナンスを自動化する

    - 最終更新日表示しリマインダーを送るなどして陳腐化を防ぐ

    - リンク有効チェック

    - Linterでのチェック

    - ドキュメントの自動生成（OpenAPIなど）

    

    View Slide

38. - 不要なコンテンツを廃止したり除去する

    - 削除するときは単に削除するのではなく、非推奨または削除されることがユー
    ザにわかるように

    - 移行ガイドがあるとベスト

    - ドキュメントはユーザにとって役に立たなくなったら削除すべき
    

    View Slide