Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Docs for Developers の読書レポート

kamimi
October 03, 2022
55

Docs for Developers の読書レポート

kamimi

October 03, 2022
Tweet

More Decks by kamimi

Transcript

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

  2. コンテンツタイプ
 - コードコメント
 - README
 - Getting started documentation
 -

    Conceptual documentation
 - Procedural documentation
 - Reference documentation
 - API reference
 - Glossary
 - Troubleshooting documentation
 - Change documentation
 ドキュメント計画のアウトラインを決める

  3. - 2つの真実
 - 読者は情報を求めて文章を見る
 - 読者はあなたが書いたものをほとんど読んでいない
 
 - 書くのに詰まる
 -

    詰まる理由が特定できれば、解決するのは簡単になる
 - テンプレから取り掛かる

  4. - コードサンプルのタイプ
 - 実行可能と説明(実行可能ではないが読者が学んだり比較する出力やコード ブロック)の2種類がある
 - 良いコードサンプルの原則
 - 説明的、正確、明瞭、役に立つ(拡張可能)、信頼できる
 -

    役に立つコードサンプルを設計する
 - 言語を選ぶ、さまざまな複雑さにフォーカスを当てる、コードをプレゼンテーショ ンする
 - ソースコードからサンプルを生成する
 

  5. - スクショを使う
 - よくある図
 - ボックスと矢印、フローチャート、スイムレーン図
 - 図を書くこと
 - 単純化


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

  6. - コンテンツのリリースプロセスの構築
 - いつどこでどうやって公開するのか
 - 公開までのタイムラインの作成
 - プロダクトのリリーススケジュールとドキュメントの公開スケジュールを調整
 - 公開の確定と承認


    - 読者へコンテンツをアナウンス
 - 利用可能な新しいリソースがあることを人々に知らせることがだいじ
 - 将来のための計画
 - ドキュメントの更新頻度、何を更新するか、リリースプロセスの改善
 

  7. - メンテナンスの計画
 - 新機能を追加するときはコードとコンテンツの両方にどのような変更を行う必 要があるかを検討すべき
 
 - 役に立つメンテナンスツール
 - メンテナンスを自動化する


    - 最終更新日表示しリマインダーを送るなどして陳腐化を防ぐ
 - リンク有効チェック
 - Linterでのチェック
 - ドキュメントの自動生成(OpenAPIなど)