$30 off During Our Annual Pro Sale. View Details »

Docs for Developers の読書レポート

kamimi
October 03, 2022
35

Docs for Developers の読書レポート

kamimi

October 03, 2022
Tweet

More Decks by kamimi

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. - 編集へのさまざまなアプローチを理解する

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

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

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

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


    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