ユーザーとの協調を重視する時代における ドキュメント制作現場の取り組み

アジャイル開発においてはマニュアルドキュメントにも開発計画の変化を前提とした制作プロセスが要求される。前半では、マニュアルをテキスト形式（Markdown）で作りGitで管理することで実現される、高速で変化に強いマニュアル制作プロセスを紹介する。
後半では、アジャイル開発の中で求められる、「フィードバックを得る場」としてのマニュアルの新たな役割を紹介する。Webマニュアルには「更新しやすい」「データを得やすい」「困っているユーザーが集まる」という特長があり、プロダクトの改善に必要なフィードバックを得る場としての新たな役割ができてきている。

Transcript

1. ユーザーとの協調を重視する時代における ドキュメント制作現場の取り組み 情報処理学会 ドキュメントコミュニケーション研究会 2019, 12月 仲田尚央（Naohiro Nakata） Cybozu 1
2. 自己紹介 テクニカルライター、UXライター、Webディレクター ⚫ 所属 ⚫ テクニカルコミュニケーションチーム ⚫ 翻訳チーム ⚫ 主な仕事： ⚫ プロダクトのUIメッセージのライティング ⚫ マニュアル・ヘルプなどのライティング ⚫ コンテンツの多言語化 仲田 尚央 なかた なおひろ @naoh_nak
3. アジャイル開発において 製品マニュアルが持つ役割 の話をします 3
4. チームワークあふれる社会を作る
5. グループウェアの開発・販売、 チームワーク研修など 5 中小企業グループウェア 業務アプリ作成プラットフォーム 大企業向けグループウェア メール共有システム 60,000社以上 10,000社以上 5,000社以上 7,500社以上
8. 話の流れ ⚫ アジャイル開発とは ⚫ アジャイル開発に対応していくために、ライティングチームがしたこと ⚫ アジャイル開発におけるマニュアルの役割 8
9. プロダクト開発プロセスの変化 9 ウォーターフォールからアジャイルへ
10. 実装 設計 計画 テスト リリース ウォーターフォール開発 アジャイル開発 テスト リリース 計画 設計 実装 イテレーション 1 テスト リリース 計画 設計 実装 テスト リリース 計画 設計 実装 イテレーション 2 イテレーション 3
11. 実装 設計 計画 テスト リリース ウォーターフォール開発 アジャイル開発 テスト リリース 計画 設計 実装 イテレーション 1 テスト リリース 計画 設計 実装 テスト リリース 計画 設計 実装 イテレーション 2 イテレーション 3 小さなリリースサイクルを繰り返す フィードバックを得ながら、仕様や開発計画を見直していく
12. 特徴 12 ⚫ウォーターフォール開発 最初に開発計画と仕様を しっかり固めて、計画通りに 進める ⚫アジャイル開発 事業の状況や関係者からの フィードバックに応じて、計画や 仕様を柔軟に変える
13. アジャイル開発が導入されると... 13 第1週 第2週 第3週 第4週 ・・・ 要件A 要件B 要件C 要件D 開発中止 開発期間延長 開発期間短縮 要件変更 開発計画の変更に柔軟に対応する マニュアル制作が必要
14. 以前のやりかた WYSIWYGなCMSによるマニュアル制作 14 書きやすいけれど、何のために どこをどう変えたのかわからない...
15. 以前のやりかた ページをPDF化して、変更点や変更理由をコメント 15
16. アジャイル開発に対応していくために 16
17. ライターを開発チームと一体に 17 プロダクトA 開発チーム プロダクトB 開発チーム プロダクトC 開発チーム ライター 開発 （PG） 品質保証 （テスター） PM & デザイン ライティング & 翻訳 ⚫ 職能別の組織を廃止 ⚫ プロダクトごとの開発チームにライターが直属 ⚫ 開発チーム内のコミュニケーションを取りやすい体制に
18. マニュアルドキュメントをバージョン管理する 18 要件Aを反映したバージョン ページ構成を改善したバージョン 要件Bを反映したバージョン 要件Cを反映したバージョン 開発計画の変更に対応して いくために ドキュメントのバージョン管理が 必要
19. バージョン管理システム ⚫ ファイルの変更履歴を記録 ⚫ いつ、誰が、どのような目的で、どのように作成/ 変更/削除したかを記録 ⚫ 複数のファイルにまたがる編集をまとめて記録 ⚫ 履歴からファイルを過去の時点に戻すことも可 ⚫ 複数人が同じファイルを同時に編集してしまっ た場合の競合を解決する仕組みも 19 ①最新のデータを 取り込み ③変更を反映 ②編集 ④変更を 取り込み
20. バージョン管理システム ⚫ 履歴を分岐して管理できる ⚫ 分岐した各枝を「ブランチ」と呼ぶ ⚫ 分岐したブランチは他のブランチの 影響を受けない ⚫ 複数の変更を並行して進められる ⚫ 他の人による変更を気にせずに変更できる ⚫ ブランチ同士を合流（マージ）させ、 変更を他のブランチに反映することもできる 20 変更 変更 変更 変更 公開版の 履歴 要件Aを反映 する履歴 ページ構成変更 の履歴 マージ
21. ドキュメントのブランチ管理 21 公開用ブランチ 要件Aリリース 要件Aを反映するブランチ 要件Bを反映するブランチ 要件Cを反映するブランチ リリースされない機能の ブランチは破棄 要件Bリリース 要件リリースに 合わせてマージ
22. ドキュメントをバージョン管理システムで管理しやすくするために ⚫ ドキュメントをテキスト形式で作る ⚫ 軽量マークアップ言語で記述 ⚫ 記述の容易さと可読性を両立 ⚫ HTMLやXMLの可読性の低さを補う目的で作られる ⚫ 記述フォーマットの例： ⚫ Markdown（サイボウズで利用） ⚫ AsciiDoc ⚫ ReStructuredText ⚫ tx2x 22
23. Markdownとは マークアップ言語のひとつ シンプルな記法で構造化された 文書を制作できる 23 # Markdownとは？ Markdownは、マークアップ言語のひとつです。シンプルな記法で 構造化された文書を手軽に制作できます。 ## Markdownで文書を作るメリット * シンプルな記法で「覚えやすい」 「書きやすい」 「読みやすい」 * ツールを選びません。テキストエディタがあれば書けます * HTMLやPDFなど各種フォーマットに変換できます ## Markdownで文書を作るには？ 1. お手持ちのテキストエディタを開き、Markdown記法で内容 を書きます。 2. 「.md」の拡張子と付けてファイルを保存します。たったこれだけ
24. Markdownのメリット ⚫ シンプルな記法で「覚えやすい」 「書きやすい」 「読みやすい」 ⚫ 読みやすいため、Markdown形式のままでもレビューが容易 ⚫ ツールを選ばない。テキストエディタがあれば書ける ⚫ 普及している ⚫ 多くの人が記法に慣れている ⚫ HTMLやPDFなどへの変換ツールが豊富 ⚫ TradosやMemsourceなどのCATツール（翻訳支援ツール）が対応 ⚫ テキストファイルなのでGitなどでのバージョン管理が容易 ⚫ 文字の一括置換が容易 24
25. MarkdownからHTMLへの変換 Hugoを利用 ⚫ HTML変換が高速 数千ページのサイトも運用可能 ⚫ Markdownの拡張が可能 「注意」「ヒント」など多彩なスタイルを表現できる 25 https://www.staticgen.com/
26. 制作システムの全体イメージ 26 GitHub 記事ファイル Memsource 翻訳メモリー 機械翻訳エンジン Circle CI Netlify ビルド ホスティング Markdown記法チェック ホスティング 文章チェック HTML化 md ①記事をPush ②チェック ②自動チェック ④翻訳元記事 を入力 学習 ⑤翻訳 ⑤翻訳 ⑥翻訳済み記事 を出力 ③&⑦ デプロイ md md md
27. マニュアル制作の流れ 27 ブランチ作成 原稿作成 GitHubに反映 Markdownで記事を作成 自動チェッカーがコメント ・ Markdownの記法をチェック ・ 文章表現の校正 要件Aを反映するための ブランチを作成
28. マニュアル制作の流れ 28 人間によるチェック 公開サイトに反映 要件Aのリリースに合わせて 公開サイトに反映 GitHub上で差分を見て 人間によるチェック
29. バージョン管理システム導入の効果 ⚫ 属人化が軽減されて、タスクを分担しやすくなった ⚫ 開発計画の変化に対応しやすくなった ⚫ 改善や修正が素早く進むようになった ⚫ 積極的に改善するようになった！手軽に編集できることは重要 29
30. アジャイル開発における マニュアルの役割 30
31. アジャイル開発の目的 31 ユーザー 開発チーム リリース フィードバック フィードバックを得ないと 短期開発を繰り返すだけになってしまう
32. アジャイル開発におけるマニュアルの役割 ユーザーの躓きポイントに先回りしてサポートしつつ ユーザーからフィードバックを得てプロダクトの改善に繋げていく 32
33. 「うまくいかないとき」に備えたデザイン 33 ディフェンシブ・ウェブデザインの技術 （毎日コミュニケーションズ, 2005） あなたがどれだけ注意深くサイトをデザイン しようと、どれほど十分にテストしようと、 訪問者は必ず問題にぶちあたるものなのだ。
34. ユーザーの「躓きポイント」に先回りする 34
35. 躓きポイントを知るために ⚫ ユーザー視点でプロダクトを見る ⚫ マニュアルを書いていると気付くことも多くある ⚫ ユーザビリティーテスト ⚫ 想像もつかないポイントでユーザーが躓くことも多くある ⚫ マニュアルで自己解決できるか確認するテストも ⚫ マニュアルのアクセスログ（後述） 35
36. フィードバックを得る場としてのマニュアル Webマニュアルの特長を活かす ⚫ 更新しやすい ⚫ データを得やすい ⚫ 困っているユーザーが集まる 36 36
37. マニュアルから得られるデータ ⚫ ページごとの閲覧数 どの機能の説明が多く参照されているか？ ⚫ 検索キーワード ユーザーはどのようなことを疑問に思っているか？ ⚫ アクセス元 プロダクトのどの画面からマニュアルを開いているか？ ⚫ アンケート ユーザーはどのような不満／要望を持っているか？ 37 マニュアルから得られるデータは プロダクト改善の貴重な根拠 になる
38. アンケートによるユーザーとのコミュニケーション 38 ユーザーが躓いた そのときに聞くことが重要
39. 事例：ログインのトラブル ⚫ ログイン画面からマニュアルへの遷移 が多く見られる ⚫ ログインに関するお問い合わせは 少ない ⚫ 問い合わせまでするユーザーは想像 以上に少ない！ ⚫ アンケートで原因を調査して改善に 繋げる 39
40. アジャイル開発において、マニュアルが持っていく役割 40 ユーザー 開発チーム リリース フィードバック 直感的でないUI、機能不足など ユーザーが躓くポイントをサポート アクセスログやアンケートデータ などからプロダクトの改善ポイ ントをフィードバック