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

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 まとめ • 開発現場が抱えるドキュメントの課題

    • 解決のため何を実現すればいいのか • 必要な情報に簡単にアクセスできるようにする • 更新しやすい状態とする • 実現のためのポイント