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

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

Naohiro Nakata
December 04, 2019

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

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

Naohiro Nakata

December 04, 2019
Tweet

More Decks by Naohiro Nakata

Other Decks in Technology

Transcript

  1. ユーザーとの協調を重視する時代における
    ドキュメント制作現場の取り組み
    情報処理学会 ドキュメントコミュニケーション研究会 2019, 12月
    仲田尚央(Naohiro Nakata)
    Cybozu
    1

    View full-size slide

  2. 自己紹介
    テクニカルライター、UXライター、Webディレクター
    ⚫ 所属
    ⚫ テクニカルコミュニケーションチーム
    ⚫ 翻訳チーム
    ⚫ 主な仕事:
    ⚫ プロダクトのUIメッセージのライティング
    ⚫ マニュアル・ヘルプなどのライティング
    ⚫ コンテンツの多言語化
    仲田 尚央
    なかた なおひろ
    @naoh_nak

    View full-size slide

  3. アジャイル開発において
    製品マニュアルが持つ役割
    の話をします
    3

    View full-size slide

  4. チームワークあふれる社会を作る

    View full-size slide

  5. グループウェアの開発・販売、 チームワーク研修など
    5
    中小企業グループウェア 業務アプリ作成プラットフォーム
    大企業向けグループウェア メール共有システム
    60,000社以上 10,000社以上
    5,000社以上 7,500社以上

    View full-size slide

  6. 話の流れ
    ⚫ アジャイル開発とは
    ⚫ アジャイル開発に対応していくために、ライティングチームがしたこと
    ⚫ アジャイル開発におけるマニュアルの役割
    8

    View full-size slide

  7. プロダクト開発プロセスの変化
    9
    ウォーターフォールからアジャイルへ

    View full-size slide

  8. 実装
    設計
    計画 テスト リリース
    ウォーターフォール開発
    アジャイル開発
    テスト
    リリース
    計画
    設計
    実装
    イテレーション
    1
    テスト
    リリース
    計画
    設計
    実装 テスト
    リリース
    計画
    設計
    実装
    イテレーション
    2
    イテレーション
    3

    View full-size slide

  9. 実装
    設計
    計画 テスト リリース
    ウォーターフォール開発
    アジャイル開発
    テスト
    リリース
    計画
    設計
    実装
    イテレーション
    1
    テスト
    リリース
    計画
    設計
    実装 テスト
    リリース
    計画
    設計
    実装
    イテレーション
    2
    イテレーション
    3
    小さなリリースサイクルを繰り返す
    フィードバックを得ながら、仕様や開発計画を見直していく

    View full-size slide

  10. 特徴
    12
    ⚫ウォーターフォール開発
    最初に開発計画と仕様を
    しっかり固めて、計画通りに
    進める
    ⚫アジャイル開発
    事業の状況や関係者からの
    フィードバックに応じて、計画や
    仕様を柔軟に変える

    View full-size slide

  11. アジャイル開発が導入されると...
    13
    第1週 第2週 第3週 第4週 ・・・
    要件A
    要件B
    要件C
    要件D 開発中止
    開発期間延長
    開発期間短縮
    要件変更
    開発計画の変更に柔軟に対応する
    マニュアル制作が必要

    View full-size slide

  12. 以前のやりかた
    WYSIWYGなCMSによるマニュアル制作
    14
    書きやすいけれど、何のために
    どこをどう変えたのかわからない...

    View full-size slide

  13. 以前のやりかた
    ページをPDF化して、変更点や変更理由をコメント
    15

    View full-size slide

  14. アジャイル開発に対応していくために
    16

    View full-size slide

  15. ライターを開発チームと一体に
    17
    プロダクトA
    開発チーム
    プロダクトB
    開発チーム
    プロダクトC
    開発チーム
    ライター
    開発
    (PG)
    品質保証
    (テスター)
    PM &
    デザイン
    ライティング &
    翻訳
    ⚫ 職能別の組織を廃止
    ⚫ プロダクトごとの開発チームにライターが直属
    ⚫ 開発チーム内のコミュニケーションを取りやすい体制に

    View full-size slide

  16. マニュアルドキュメントをバージョン管理する
    18
    要件Aを反映したバージョン
    ページ構成を改善したバージョン
    要件Bを反映したバージョン
    要件Cを反映したバージョン
    開発計画の変更に対応して
    いくために
    ドキュメントのバージョン管理が
    必要

    View full-size slide

  17. バージョン管理システム
    ⚫ ファイルの変更履歴を記録
    ⚫ いつ、誰が、どのような目的で、どのように作成/
    変更/削除したかを記録
    ⚫ 複数のファイルにまたがる編集をまとめて記録
    ⚫ 履歴からファイルを過去の時点に戻すことも可
    ⚫ 複数人が同じファイルを同時に編集してしまっ
    た場合の競合を解決する仕組みも
    19
    ①最新のデータを
    取り込み
    ③変更を反映
    ②編集
    ④変更を
    取り込み

    View full-size slide

  18. バージョン管理システム
    ⚫ 履歴を分岐して管理できる
    ⚫ 分岐した各枝を「ブランチ」と呼ぶ
    ⚫ 分岐したブランチは他のブランチの
    影響を受けない
    ⚫ 複数の変更を並行して進められる
    ⚫ 他の人による変更を気にせずに変更できる
    ⚫ ブランチ同士を合流(マージ)させ、
    変更を他のブランチに反映することもできる
    20
    変更 変更
    変更 変更
    公開版の
    履歴
    要件Aを反映
    する履歴
    ページ構成変更
    の履歴
    マージ

    View full-size slide

  19. ドキュメントのブランチ管理
    21
    公開用ブランチ
    要件Aリリース
    要件Aを反映するブランチ
    要件Bを反映するブランチ
    要件Cを反映するブランチ
    リリースされない機能の
    ブランチは破棄
    要件Bリリース
    要件リリースに
    合わせてマージ

    View full-size slide

  20. ドキュメントをバージョン管理システムで管理しやすくするために
    ⚫ ドキュメントをテキスト形式で作る
    ⚫ 軽量マークアップ言語で記述
    ⚫ 記述の容易さと可読性を両立
    ⚫ HTMLやXMLの可読性の低さを補う目的で作られる
    ⚫ 記述フォーマットの例:
    ⚫ Markdown(サイボウズで利用)
    ⚫ AsciiDoc
    ⚫ ReStructuredText
    ⚫ tx2x
    22

    View full-size slide

  21. Markdownとは
    マークアップ言語のひとつ
    シンプルな記法で構造化された
    文書を制作できる
    23
    # Markdownとは?
    Markdownは、マークアップ言語のひとつです。シンプルな記法で
    構造化された文書を手軽に制作できます。
    ## Markdownで文書を作るメリット
    * シンプルな記法で「覚えやすい」 「書きやすい」 「読みやすい」
    * ツールを選びません。テキストエディタがあれば書けます
    * HTMLやPDFなど各種フォーマットに変換できます
    ## Markdownで文書を作るには?
    1. お手持ちのテキストエディタを開き、Markdown記法で内容
    を書きます。
    2. 「.md」の拡張子と付けてファイルを保存します。たったこれだけ

    View full-size slide

  22. Markdownのメリット
    ⚫ シンプルな記法で「覚えやすい」 「書きやすい」 「読みやすい」
    ⚫ 読みやすいため、Markdown形式のままでもレビューが容易
    ⚫ ツールを選ばない。テキストエディタがあれば書ける
    ⚫ 普及している
    ⚫ 多くの人が記法に慣れている
    ⚫ HTMLやPDFなどへの変換ツールが豊富
    ⚫ TradosやMemsourceなどのCATツール(翻訳支援ツール)が対応
    ⚫ テキストファイルなのでGitなどでのバージョン管理が容易
    ⚫ 文字の一括置換が容易
    24

    View full-size slide

  23. MarkdownからHTMLへの変換
    Hugoを利用
    ⚫ HTML変換が高速
    数千ページのサイトも運用可能
    ⚫ Markdownの拡張が可能
    「注意」「ヒント」など多彩なスタイルを表現できる
    25
    https://www.staticgen.com/

    View full-size slide

  24. 制作システムの全体イメージ
    26
    GitHub
    記事ファイル
    Memsource
    翻訳メモリー 機械翻訳エンジン
    Circle CI
    Netlify
    ビルド
    ホスティング
    Markdown記法チェック
    ホスティング
    文章チェック
    HTML化
    md
    ①記事をPush
    ②チェック ②自動チェック
    ④翻訳元記事
    を入力
    学習
    ⑤翻訳
    ⑤翻訳
    ⑥翻訳済み記事
    を出力
    ③&⑦
    デプロイ
    md
    md
    md

    View full-size slide

  25. マニュアル制作の流れ
    27
    ブランチ作成 原稿作成 GitHubに反映
    Markdownで記事を作成
    自動チェッカーがコメント
    ・ Markdownの記法をチェック
    ・ 文章表現の校正
    要件Aを反映するための
    ブランチを作成

    View full-size slide

  26. マニュアル制作の流れ
    28
    人間によるチェック 公開サイトに反映
    要件Aのリリースに合わせて
    公開サイトに反映
    GitHub上で差分を見て
    人間によるチェック

    View full-size slide

  27. バージョン管理システム導入の効果
    ⚫ 属人化が軽減されて、タスクを分担しやすくなった
    ⚫ 開発計画の変化に対応しやすくなった
    ⚫ 改善や修正が素早く進むようになった
    ⚫ 積極的に改善するようになった!手軽に編集できることは重要
    29

    View full-size slide

  28. アジャイル開発における
    マニュアルの役割
    30

    View full-size slide

  29. アジャイル開発の目的
    31
    ユーザー
    開発チーム
    リリース
    フィードバック
    フィードバックを得ないと
    短期開発を繰り返すだけになってしまう

    View full-size slide

  30. アジャイル開発におけるマニュアルの役割
    ユーザーの躓きポイントに先回りしてサポートしつつ
    ユーザーからフィードバックを得てプロダクトの改善に繋げていく
    32

    View full-size slide

  31. 「うまくいかないとき」に備えたデザイン
    33
    ディフェンシブ・ウェブデザインの技術
    (毎日コミュニケーションズ, 2005)
    あなたがどれだけ注意深くサイトをデザイン
    しようと、どれほど十分にテストしようと、
    訪問者は必ず問題にぶちあたるものなのだ。

    View full-size slide

  32. ユーザーの「躓きポイント」に先回りする
    34

    View full-size slide

  33. 躓きポイントを知るために
    ⚫ ユーザー視点でプロダクトを見る
    ⚫ マニュアルを書いていると気付くことも多くある
    ⚫ ユーザビリティーテスト
    ⚫ 想像もつかないポイントでユーザーが躓くことも多くある
    ⚫ マニュアルで自己解決できるか確認するテストも
    ⚫ マニュアルのアクセスログ(後述)
    35

    View full-size slide

  34. フィードバックを得る場としてのマニュアル
    Webマニュアルの特長を活かす
    ⚫ 更新しやすい
    ⚫ データを得やすい
    ⚫ 困っているユーザーが集まる
    36
    36

    View full-size slide

  35. マニュアルから得られるデータ
    ⚫ ページごとの閲覧数
    どの機能の説明が多く参照されているか?
    ⚫ 検索キーワード
    ユーザーはどのようなことを疑問に思っているか?
    ⚫ アクセス元
    プロダクトのどの画面からマニュアルを開いているか?
    ⚫ アンケート
    ユーザーはどのような不満/要望を持っているか?
    37
    マニュアルから得られるデータは
    プロダクト改善の貴重な根拠
    になる

    View full-size slide

  36. アンケートによるユーザーとのコミュニケーション
    38
    ユーザーが躓いた
    そのときに聞くことが重要

    View full-size slide

  37. 事例:ログインのトラブル
    ⚫ ログイン画面からマニュアルへの遷移
    が多く見られる
    ⚫ ログインに関するお問い合わせは
    少ない
    ⚫ 問い合わせまでするユーザーは想像
    以上に少ない!
    ⚫ アンケートで原因を調査して改善に
    繋げる
    39

    View full-size slide

  38. アジャイル開発において、マニュアルが持っていく役割
    40
    ユーザー
    開発チーム
    リリース
    フィードバック
    直感的でないUI、機能不足など
    ユーザーが躓くポイントをサポート
    アクセスログやアンケートデータ
    などからプロダクトの改善ポイ
    ントをフィードバック

    View full-size slide