Yappliの仕様書整備を例とした情報整理の考えかた / How To Struct Information: A Case Study of Yappli's Specification Management

Yappli Tech Conference 2023 登壇資料

connpass:
https://yappli.connpass.com/event/295001/

セッション動画（YouTube:）
https://youtu.be/Va29Zkd5a50?si=R28c4WaGO0pAKAPr

Transcript

1. Yappliの仕様書整備を 例とした 情報整理の考えかた
2. Speaker プロダクト開発本部 開発企画部 テクニカルライター 渋 谷 力 人 ドキュメント制作会社でPCなど電 子 機器のマニュア ル制作を経験。 2020年10 月 ヤプリに 入 社。
3. はじめに 今回の内容 • テクニカルライターは何をしているのか（簡単に） • 情報をまとめるͨΊͷߟ͔͑ͨʢYappliの仕様書整備を例に） → 前提として、Yappliの表側（フロント）部分の情報をまとめる話 • 伝わる 文 章の具体的な書きかた • 仕様書整備においてどのような仕組みやフローを採 用 しているのか 含まれないもの 00 はじめに
4. 01 02 03 04 テクニカルライターは何をしている 開発におけるドキュメントの課題 整理するためのポイント まとめ
5. 01 テクニカルライターは 何をしている
6. 01 テクニカルライターは何をしている 情報を 目 的 ・ 読者に合わせて 簡潔に 一 意で伝わるようにする
7. 架空のプロ野球の説明 日 本プロベースボールアライアンス（JPBA）は、アートディビジョンとエステディビジョンに分かれてい る。 アートディビジョンの所属チームは、東京ドラゴンズ （1930年）、 大 阪サムライズ （1955年）、札幌スノ ウキャッツ （1968年）、福岡ファイヤーフォックス （1973年）、名古屋サイクロンズ （1981年）、京都 チェリーブロッサムズ （1990年）。 エステディビジョンには、横浜ハーバーシャークス （1952年）、仙台ソーラースターズ （1965年）、広島 ブラックキャッツ（1977年）、 長 野アルパインズ （1983年）、熊本ロイヤルファイターズ（1998年）、 沖縄コーラルスピリッツ（2005年）が所属している。 ＊（ ）のは創設年。 01 テクニカルライターは何をしている
8. 例えばこうする 日 本プロベースボールアライアンス（JPBA）のディビジョン ・ 所属チーム ・ 創設年 チーム名 創設年 東京ドラゴンズ 1930年 大 阪サムライズ 1955年 札幌スノウキャッツ 1968年 福岡ファイヤーフォックス 1973年 名古屋サイクロンズ 1981年 京都チェリーブロッサムズ 1990年 アートディビジョン エステディビジョン チーム名 創設年 横浜ハーバーシャークス 1952年 仙台ソーラースターズ 1955年 広島ブラックキャッツ 1977年 長 野アルパインズ 1983年 熊本ロイヤルファイターズ 1998年 沖縄コーラルスピリッツ 2005年 01 テクニカルライターは何をしている
9. 文 章を書くだけではない • 文 章を考える • 構成 面 を含めまとめかたを考える ⇒ 後者が先で重要 01 テクニカルライターは何をしている
10. 02 開発における ドキュメントの課題
11. 開発現場あるある（課題） • ドキュメントがどこにあるのかわからない • 似た名前 ・ 内容のドキュメントが存在する • ページのどこに書いてあるかわかりづらい • 更新されず内容が最新かわからない 02 開発におけるドキュメントの課題
12. ドキュメントが整備されていないと • 探すためのコスト • コミュニケーションコストの増加 • 誤った情報の伝達 • 属 人 化、引き継ぎの問題 • プロダクトの不具合の原因となる可能性 02 開発におけるドキュメントの課題
13. 業務に様々な影響を与える 実際にYappli開発でも ・・・ 02 開発におけるドキュメントの課題
14. 開発単位でドキュメントが存在 電 子 書籍機能まとめ 電 子 書籍機能 電 子 書籍リニューアル対応について 新電 子 書籍Phase 1 対応 電 子 書籍 02 開発におけるドキュメントの課題
15. 要因 • アジャイル開発 • 案件ごとに仕様情報が存在する → アクセスの問題 • 年間アップデート数の多さ • 短いサイクルで古い情報となる → 更新の問題 02 開発におけるドキュメントの課題
16. 開発現場あるある（課題） • ドキュメントがどこにあるのかわからない • 似た名前 ・ 内容のドキュメントが存在する • ページのどこに書いてあるかわかりづらい • 更新されず内容が最新かわからない 02 開発におけるドキュメントの課題 → アクセスの問題 → 更新の問題
17. 課題解決のため 目 指すこと • 必要な情報に簡単にアクセスできるようにする • 更新しやすい状態にする 02 開発におけるドキュメントの課題
18. 開発案件ごとにまとめるいい 方 法はあるか？ 開発体制フローは？ プロダクトの特徴は？ 情報はどのように降りてくる？ Yappliで実現するには 02 開発におけるドキュメントの課題
19. 開発案件単位 ↓ 機能単位でまとめて整理する 02 開発におけるドキュメントの課題
20. 03 整理するためのポイント
21. 前提 • Yappli CMSの表側（フロント）の情報をまとめる 03 整理するためのポイント
22. 整理するためのポイント 1 . 場所とカテゴリー 2 . タイトルの具体化 3 . レイアウトと 見 出し 03 整理するためのポイント
23. ポイント 1 場所とカテゴリー 03 整理するためのポイント
24. 課題 • ドキュメントがどこにあるのかわからない • 似た名前 ・ 内容のドキュメントが存在する • ページのどこに書いてあるかわかりづらい • 更新されず内容が最新かわからない 03 整理するためのポイント
25. 場所：スペースを新設して集約 • ヤプリではConfluenceを使 用 • プロダクト開発本部にも専 用 スペースが存在 • スペース内に約5,000ページ存在 • Confluenceではスペースに絞った検索が可能 03 整理するためのポイント
26. カテゴリー：プロダクトとの親和性 • グローバルナビ • 機能 • プッシュ通知 • 外部連携 ・・・ 03 整理するためのポイント
27. 03 整理するためのポイント
28. 課題 • ドキュメントがどこにあるのかわからない • 似た名前 ・ 内容のドキュメントが存在する • ページのどこに書いてあるかわかりづらい • 更新されず内容が最新かわからない 03 整理するためのポイント
29. ポイント 2 タイトルの具体化 03 整理するためのポイント
30. 課題 • ドキュメントがどこにあるのかわからない • 似た名前 ・ 内容のドキュメントが存在する • ページのどこに書いてあるかわかりづらい • 更新されず内容が最新かわからない 03 整理するためのポイント
31. タイトルを具体化することで差別化する 03 整理するためのポイント
32. タイトルを具体化できない スタンプカード 基本情報 見 出し CMS 見 出し 見 出し アプリ 見 出し 見 出し 左の場合、1つのページに「基本情報」「CMS」 「アプリ」の情報を含んでいる。 異なる要素の情報が存在するため、タイトルを具体化 できず 大 枠の「スタンプカード」となる。 具体的なタイトルでないため、同じような ドキュメントの存在につながることがある 03 整理するためのポイント
33. 情報の 一 元管理とは 1箇所に情報を詰め込むことではない 03 整理するためのポイント
34. ページを分けてタイトルを具体化 スタンプカード 基本情報 見 出し CMS 見 出し 見 出し アプリ 見 出し 見 出し 基本情報 見 出し CMS 見 出し 見 出し アプリ 見 出し 見 出し 03 整理するためのポイント
35. 考慮ポイント • ページを分けることで記載内容が絞られるため、タイトルを具体化できる • 細かく分ければ分けるほど、タイトルは具体化していく • ただし、ページが増えれば増えるほど管理は 大 変になる ⇒ 必要に応じて適切に少しずつ細分化していく 03 整理するためのポイント
36. 03 整理するためのポイント
37. 課題 • ドキュメントがどこにあるのかわからない • 似た名前 ・ 内容のドキュメントが存在する • ページのどこに書いてあるかわかりづらい • 更新されず内容が最新かわからない 03 整理するためのポイント
38. ポイント3 レイアウトと 見 出し 03 整理するためのポイント
39. 課題 • ドキュメントがどこにあるのかわからない • 似た名前 ・ 内容のドキュメントが存在する • ページのどこに書いてあるかわかりづらい • 更新されず内容が最新かわからない 03 整理するためのポイント
40. 統 一 感と可読性 • 基本情報のページ • 表組み • CMS ／ アプリのページ • 1：2、左が画像、右が説明 • 見 出しを必ずつける 03 整理するためのポイント
41. 目 次 見 出し1 　 画像 　 説明 見 出し2 　 画像 　 説明 見 出し3 　 画像 　 説明 03 整理するためのポイント
42. 03 整理するためのポイント
43. 03 整理するためのポイント
44. 情報を探す スタンプカード • スタンプカード：基本情報 ・ 注意事項 • スタンプカード：CMS「カード登録」 • スタンプカード：CMS「スタンプ登録」 • スタンプカード：CMS「設定」 • スタンプカード：アプリ スタンプカードのアプリの〇〇を知りたいから 03 整理するためのポイント
45. 慣れると推測しやすくなる アプリのページのあの辺りかな スタンプカード • スタンプカード：基本情報 ・ 注意事項 • スタンプカード：CMS「カード登録」 • スタンプカード：CMS「スタンプ登録」 • スタンプカード：CMS「設定」 • スタンプカード：アプリ 03 整理するためのポイント
46. 課題 • ドキュメントがどこにあるのかわからない • 似た名前 ・ 内容のドキュメントが存在する • ページのどこに書いてあるかわかりづらい • 更新されず内容が最新かわからない 03 整理するためのポイント
47. 整理するためのポイント 1 . 場所とカテゴリー 2 . タイトルの具体化 3 . レイアウトと 見 出し 03 整理するためのポイント
48. 更新のしやすさは 3つのポイントに含まれている 03 整理するためのポイント
49. 必要な情報に簡単にアクセスできない ことが更新できない要因の1つ 03 整理するためのポイント
50. 情報を探す 人 はだれか • 情報を知りたい 人 • 情報をまとめる 人 💡 03 整理するためのポイント
51. まとめる側もアクセスしやすい スタンプカード • スタンプカード：基本情報 ・ 注意事項 • スタンプカード：CMS「カード登録」 • スタンプカード：CMS「スタンプ登録」 • スタンプカード：CMS「設定」 • スタンプカード：アプリ 03 整理するためのポイント
52. 課題をすべておさえた • ドキュメントがどこにあるのかわからない • 似た名前 ・ 内容のドキュメントが存在する • ページのどこに書いてあるかわかりづらい • 更新されず内容が最新かわからない 03 整理するためのポイント
53. ここから実際に情報整理を進めていく 03 整理するためのポイント
54. 04 まとめ
55. まとめ 今回の内容 • テクニカルライターは何をしているのか（簡単に） • 情報をまとめるͨΊͷߟ͔͑ͨʢYappliの仕様書整備を例に） 04 まとめ • 開発現場が抱えるドキュメントの課題 • 解決のため何を実現すればいいのか • 必要な情報に簡単にアクセスできるようにする • 更新しやすい状態とする • 実現のためのポイント