『THE PRODUCT IS DOCS』のすゝめ

書籍『THE PRODUCT IS DOCS』の紹介です。アジャイル開発の現場におけるドキュメント制作や、そのチームのあり方にフォーカスした書籍です。
「LINE Technical Writing Meetup vol. 19 ~ 年納め LT パーティ」での発表資料。

Transcript

1. THE PRODUCT IS DOCS のすゝめ
   仲田 尚央
   2022年12月21日 LINE Technical Writing Meetup vol. 19 ~ 年納めLTパーティ
   1
   

   View Slide

2. 2
   仲田 尚央
   Nakata Naohiro
   @naoh_nak
   サイボウズ
   テクニカルライター/ローカライズ 職能マネージャー
   お仕事の内容：
   ⚫ サイボウズ製品のUIテキストを書く
   ⚫ 製品のマニュアルやヘルプを書く
   ⚫ それらを他の言語に展開する（ローカライズ）
   副業でライティング講習もしています
   

   View Slide

3. 『THE PRODUCT IS DOCS』について
   今日は、今年読んで良かった書籍『THE PRODUCT IS DOCS』
   を紹介します
   ⚫ アメリカのソフトウェア開発企業 Splunk社のテクニカルライターたち
   が執筆
   ⚫ アジャイル開発の現場におけるドキュメント制作や、そのチームのあ
   り方にフォーカスした本
   ⚫ Splunk社のドキュメントチームが日々の活動で学んだベストプラク
   ティスをまとめている
   ⚫ 英語...
   3
   

   View Slide

4. 本書の目次
   1. Introduction（はじめに）
   2. Agile（アジャイル）
   3. Audience（読者）
   4. Collaborative Authoring（複数のライターでの協力）
   5. Customer Feedback and Community（顧客からのフィードバックとコ
   ミュニティー）
   6. Documentation Decisions（ドキュメントに関する決定）
   7. Documenting Third-party Products（サードパーティー製品のドキュ
   メント）
   8. Hiring, Training, and Managing Documentation Teams（ド
   キュメントチームの採用、トレーニング、マネジメント）
   9. Learning Objectives（学習目標）
   10. Maintaining Existing Content（既存コンテンツのメンテナンス）
   11. Measuring Success（成果の計測）
   12. Organizing Documentation Tiger Teams（ドキュメントの緊急対
   応チーム）
   13. Research for Technical Writers（情報の集め方）
   4
   14. Scenario-driven Information Development（シナリオ駆
   動でのドキュメント制作）
   15. Technical Editing（ドキュメントの校正）
   16. Technical Verification（ドキュメントの正しさチェック）
   17. Tools and Content Delivery（ツールとコンテンツデリバリー）
   18. Working with Customer Support（カスタマーサポートとの協力）
   19. Working with Engineers（エンジニアとの協力）
   20. Working with the Field（現場との協力）
   21. Working with Marketing（マーケッターとの協力）
   22. Working with Product Management（PdMとの協力） ）
   23. Working with Remote Teams（リモート開発チームとの協力）
   24. Working with User Experience and Design（UX、デザイナー
   との協力）
   25. Writing SaaS Documentation（SaaSのドキュメント制作）
   26. Afterword and Acknowledgments（あと書きと謝辞）
   

   View Slide

5. この本が想定するテクニカルライター
   5
   プロダクト寄りの
   テクニカルライター
   技術寄りの
   テクニカルライター
   本書は、こちらの話がメイン
   ホワイトペーパー、
   APIドキュメントなど制作
   製品マニュアル、
   リリースノートなど制作
   

   View Slide

6. 英語だし長いので、輪読形式に
   6
   ⚫ SmartHRさんと共同で輪読会を実施
   ⚫ 週に1章ずつ
   LINEさん、すみません💧
   

   View Slide

7. 印象に残ったところを一部抜粋して紹介
   7
   

   View Slide

8. テクニカルライターとしての素質
   ⚫ テクニカルライターの仕事の本質は、文章を書くことでも、
   技術を学ぶことでもない
   ⚫ 人間関係の仕事であり、ジャーナリズムに他ならない
   ⚫ 好奇心 ＋ 情報を整理するスキル ＋ 書くスキル
   ⚫ テクニカルライターの特性：
   ⚫ 柔軟さ（flexible）
   ⚫ 恐れない（fearless）
   ⚫ 魅力がある（personable）
   ⚫ 組織立っている（organized）
   ⚫ 豊富な経験を持った（experimental）
   ⚫ 顧客に目を向ける（customer-focused）
   ⚫ 総合力が高い（Generalists）
   8
   ❝Resourcefulness and eagerness
   are essential. When you screen
   tech writer candidates, look for a
   real appetite for discovery. The
   job, fundamentally, isn’t about
   writing or learning technology.
   It’s a relationship business, more
   like investigative journalism than
   anything else.❞
   『THE PRODUCT IS DOCS』 8章より
   

   View Slide

9. テクニカルライターの情報収集 1/2
   ⚫ 情報収集に時間を掛ける
   ⚫ 製品の領域について
   ⚫ 製品の背景（なぜこの製品が必要なのか）
   ⚫ 技術
   ⚫ 業務
   ⚫ 各分野の専門家を訪ねよう
   自分が専門家になる必要はない
   9
   『THE PRODUCT IS DOCS』 2章より
   

   View Slide

10. テクニカルライターの情報収集 2/2
    ⚫ 一次資料から書く
    ⚫ 見つからない場合は、複数のソースでファクトチェックする
    ⚫ 自分で製品を触る
    ⚫ 触らないとわからない情報もある
    ⚫ 自分で触らずに開発者に仕様確認すると、信頼を失うことも
    ⚫ 起こったことを、そのまま記録する
    ⚫ エラーを起こしそうな操作を試して、どうなるかを見る
    10
    

    View Slide

11. 関係者へのインタビュー
    資料だけでなく、関係者の話も重要な情報源
    ⚫ 適切な相手
    ⚫ プロダクトマネージャー、QA、サポートエンジニア
    ⚫ ユーザー
    ⚫ 話しを引き出すコツ
    ⚫ まず自己紹介から（挨拶しなさいって、ばあちゃんが言ってた）
    ⚫ 「なぜその話を聞きたいのか」という背景も伝える（相手への共感は大事）
    ⚫ すぐにできない回答には、期限を設ける（仕事に期限は付きもの）
    ⚫ 正攻法がうまくいかないときは、反応せざるを得ない間違ったことを書いてみる（そこまでする...？）
    11
    

    View Slide

12. Scrum of writers
    メリット
    ⚫ ライター同士の連携や助け合いが容易
    ⚫ ドキュメントに関する相談先が明確
    ⚫ ナレッジが蓄積される
    デメリット
    ⚫ 開発工程に対して下流からの関わりになる
    ⚫ ドキュメントに書かれない情報を得づらい
    Direct participation
    メリット
    ⚫ 活動領域が広がる（UIテキスト、用語など）
    ⚫ ドキュメントへの影響を含めて開発タスクを検討できる
    ⚫ 開発チームとの情報共有が円滑になる
    デメリット
    ⚫ 情報やナレッジがサイロ化する
    ⚫ ライター同士の連携や助け合いが難しい
    アジャイル/スクラム開発の中で、ライターがどこに属すか
    12
    スクラムA
    PdM
    プログラマー
    デザイナー
    ライター
    スクラムB
    PdM
    プログラマー
    デザイナー
    ライター
    スクラムC
    PdM
    プログラマー
    デザイナー
    ライター
    スクラムA
    PdM
    プログラマー
    デザイナー
    テスタ－
    スクラムB
    PdM
    プログラマー
    デザイナー
    テスター
    ライターチーム
    ライター
    ライター
    ライター
    ライター
    

    View Slide

13. よりアジャイルになるために
    よりアジャイルになるためには、人との関係作りが何より重要
    ⚫ 可能であれば、スクラム開発チームにライターが所属しよう
    ⚫ 可能な限り多くのミーティングに参加しよう
    ⚫ プランニング、スプリントレビュー、振り返り、など
    ⚫ 対面でのコミュニケーションを重視しよう
    ⚫ 開発チームと同じツールを使おう
    ⚫ タスク管理、ドキュメントレビューなど
    ⚫ 開発タスクのチケットに、ドキュメントの優先度や工数も書こう
    ⚫ 開発タスクの完了の定義に、ドキュメンテーションを含めよう
    ⚫ ドキュメントまで含めて、スプリントごとにリリースするのが理想
    ⚫ シナリオベースのユーザーストーリーをプロダクトマネージャーと共有しよう
    13
    ❝For technical writers, being Agile
    is more about relationship-building
    than anything else.❞
    『THE PRODUCT IS DOCS』 2章より
    

    View Slide

14. ユーザーからのフィードバック
    ユーザーとの対話により、自分が作ったドキュメントが目的を達成できて
    いるかについての洞察を得られる
    ⚫ ユーザーからのフィードバックを集める手段
    ⚫ SNS
    ⚫ ドキュメントに設置したフォーム
    ⚫ ユーザー会でのアンケート
    ⚫ ユーザーリサーチやユーザビリティーテスト
    ⚫ ユーザーからのフィードバックを活かす
    ⚫ エントリーユーザーが使い始めに困っていたら
    👉記事を追加したり、ナビゲーションを改善する必要があるかも
    ⚫ 上級ユーザーが必要な詳細情報を見つけられていなかったら
    👉用語やメンタルモデルが、彼らと合っていないのかも
    ⚫ 同じお問い合わせが何度も来ていたら
    👉ドキュメントに書く。すでに書いてあるなら、なぜその記事を見つけられないのか分析する 14
    In the case of documentation,
    the ire mostly stems from
    inadequate or incomplete
    documentation.
    『THE PRODUCT IS DOCS』 5章より
    

    View Slide

15. 終わりに
    ⚫ 製品開発組織の中でのドキュメントチームにフォーカスした本は貴重
    ⚫ 似た立場にいるテクニカルライターの方にオススメの本
    ⚫ 今回紹介した内容のほかにも、参考になるアイデアが多い
    ⚫ テクニカルライター（やUXライター）は、開発組織にとって＋α（nice to have）の要素だと思っています
    ⚫ だからこそ、ライターは能動的に動いていかなければならない
    ⚫ 情報が降ってくるのを待っていてはダメ
    15
    （本著に書かれているように）
    ジャーナリストとしてのハングリー精神を持っていこう
    

    View Slide

16. 良
    い
    お
    年
    を
    お
    迎
    え
    く
    だ
    さ
    い
    

    View Slide