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

by Yappli Developers

Slide 1

Slide 1 text

Yappliの仕様書整備を例とした情報整理の考えかた

Slide 2

Slide 2 text

Speaker プロダクト開発本部開発企画部テクニカルライター渋谷力人ドキュメント制作会社でPCなど電子機器のマニュアル制作を経験。 2020年10 月ヤプリに入社。

Slide 3

Slide 3 text

はじめに今回の内容 • テクニカルライターは何をしているのか（簡単に） • 情報をまとめるͨΊͷߟ͔͑ͨʢYappliの仕様書整備を例に） → 前提として、Yappliの表側（フロント）部分の情報をまとめる話 • 伝わる文章の具体的な書きかた • 仕様書整備においてどのような仕組みやフローを採用しているのか含まれないもの 00 はじめに

Slide 4

Slide 4 text

01 02 03 04 テクニカルライターは何をしている開発におけるドキュメントの課題整理するためのポイントまとめ

Slide 5

Slide 5 text

01 テクニカルライターは何をしている

Slide 6

Slide 6 text

01 テクニカルライターは何をしている情報を目的・読者に合わせて簡潔に一意で伝わるようにする

Slide 7

Slide 7 text

架空のプロ野球の説明日本プロベースボールアライアンス（JPBA）は、アートディビジョンとエステディビジョンに分かれている。アートディビジョンの所属チームは、東京ドラゴンズ（1930年）、大阪サムライズ（1955年）、札幌スノウキャッツ（1968年）、福岡ファイヤーフォックス（1973年）、名古屋サイクロンズ（1981年）、京都チェリーブロッサムズ（1990年）。エステディビジョンには、横浜ハーバーシャークス（1952年）、仙台ソーラースターズ（1965年）、広島ブラックキャッツ（1977年）、長野アルパインズ（1983年）、熊本ロイヤルファイターズ（1998年）、沖縄コーラルスピリッツ（2005年）が所属している。＊（）のは創設年。 01 テクニカルライターは何をしている

Slide 8

Slide 8 text

例えばこうする日本プロベースボールアライアンス（JPBA）のディビジョン・所属チーム・創設年チーム名創設年東京ドラゴンズ 1930年大阪サムライズ 1955年札幌スノウキャッツ 1968年福岡ファイヤーフォックス 1973年名古屋サイクロンズ 1981年京都チェリーブロッサムズ 1990年アートディビジョンエステディビジョンチーム名創設年横浜ハーバーシャークス 1952年仙台ソーラースターズ 1955年広島ブラックキャッツ 1977年長野アルパインズ 1983年熊本ロイヤルファイターズ 1998年沖縄コーラルスピリッツ 2005年 01 テクニカルライターは何をしている

Slide 9

Slide 9 text

文章を書くだけではない • 文章を考える • 構成面を含めまとめかたを考える ⇒ 後者が先で重要 01 テクニカルライターは何をしている

Slide 10

Slide 10 text

02 開発におけるドキュメントの課題

Slide 11

Slide 11 text

開発現場あるある（課題） • ドキュメントがどこにあるのかわからない • 似た名前・内容のドキュメントが存在する • ページのどこに書いてあるかわかりづらい • 更新されず内容が最新かわからない 02 開発におけるドキュメントの課題

Slide 12

Slide 12 text

ドキュメントが整備されていないと • 探すためのコスト • コミュニケーションコストの増加 • 誤った情報の伝達 • 属人化、引き継ぎの問題 • プロダクトの不具合の原因となる可能性 02 開発におけるドキュメントの課題

Slide 13

Slide 13 text

業務に様々な影響を与える実際にYappli開発でも・・・ 02 開発におけるドキュメントの課題

Slide 14

Slide 14 text

開発単位でドキュメントが存在電子書籍機能まとめ電子書籍機能電子書籍リニューアル対応について新電子書籍Phase 1 対応電子書籍 02 開発におけるドキュメントの課題

Slide 15

Slide 15 text

要因 • アジャイル開発 • 案件ごとに仕様情報が存在する → アクセスの問題 • 年間アップデート数の多さ • 短いサイクルで古い情報となる → 更新の問題 02 開発におけるドキュメントの課題

Slide 16

Slide 16 text

開発現場あるある（課題） • ドキュメントがどこにあるのかわからない • 似た名前・内容のドキュメントが存在する • ページのどこに書いてあるかわかりづらい • 更新されず内容が最新かわからない 02 開発におけるドキュメントの課題 → アクセスの問題 → 更新の問題

Slide 17

Slide 17 text

課題解決のため目指すこと • 必要な情報に簡単にアクセスできるようにする • 更新しやすい状態にする 02 開発におけるドキュメントの課題

Slide 18

Slide 18 text

開発案件ごとにまとめるいい方法はあるか？開発体制フローは？プロダクトの特徴は？情報はどのように降りてくる？ Yappliで実現するには 02 開発におけるドキュメントの課題

Slide 19

Slide 19 text

開発案件単位 ↓ 機能単位でまとめて整理する 02 開発におけるドキュメントの課題

Slide 20

Slide 20 text

03 整理するためのポイント

Slide 21

Slide 21 text

前提 • Yappli CMSの表側（フロント）の情報をまとめる 03 整理するためのポイント

Slide 22

Slide 22 text

整理するためのポイント 1 . 場所とカテゴリー 2 . タイトルの具体化 3 . レイアウトと見出し 03 整理するためのポイント

Slide 23

Slide 23 text

ポイント 1 場所とカテゴリー 03 整理するためのポイント

Slide 24

Slide 24 text

課題 • ドキュメントがどこにあるのかわからない • 似た名前・内容のドキュメントが存在する • ページのどこに書いてあるかわかりづらい • 更新されず内容が最新かわからない 03 整理するためのポイント

Slide 25

Slide 25 text

場所：スペースを新設して集約 • ヤプリではConfluenceを使用 • プロダクト開発本部にも専用スペースが存在 • スペース内に約5,000ページ存在 • Confluenceではスペースに絞った検索が可能 03 整理するためのポイント

Slide 26

Slide 26 text

カテゴリー：プロダクトとの親和性 • グローバルナビ • 機能 • プッシュ通知 • 外部連携・・・ 03 整理するためのポイント

Slide 27

Slide 27 text

03 整理するためのポイント

Slide 28

Slide 28 text

Slide 29

Slide 29 text

ポイント 2 タイトルの具体化 03 整理するためのポイント

Slide 30

Slide 30 text

Slide 31

Slide 31 text

タイトルを具体化することで差別化する 03 整理するためのポイント

Slide 32

Slide 32 text

タイトルを具体化できないスタンプカード基本情報見出し CMS 見出し見出しアプリ見出し見出し左の場合、1つのページに「基本情報」「CMS」「アプリ」の情報を含んでいる。異なる要素の情報が存在するため、タイトルを具体化できず大枠の「スタンプカード」となる。具体的なタイトルでないため、同じようなドキュメントの存在につながることがある 03 整理するためのポイント

Slide 33

Slide 33 text

情報の一元管理とは 1箇所に情報を詰め込むことではない 03 整理するためのポイント

Slide 34

Slide 34 text

ページを分けてタイトルを具体化スタンプカード基本情報見出し CMS 見出し見出しアプリ見出し見出し基本情報見出し CMS 見出し見出しアプリ見出し見出し 03 整理するためのポイント

Slide 35

Slide 35 text

考慮ポイント • ページを分けることで記載内容が絞られるため、タイトルを具体化できる • 細かく分ければ分けるほど、タイトルは具体化していく • ただし、ページが増えれば増えるほど管理は大変になる ⇒ 必要に応じて適切に少しずつ細分化していく 03 整理するためのポイント

Slide 36

Slide 36 text

03 整理するためのポイント

Slide 37

Slide 37 text

Slide 38

Slide 38 text

ポイント3 レイアウトと見出し 03 整理するためのポイント

Slide 39

Slide 39 text

Slide 40

Slide 40 text

統一感と可読性 • 基本情報のページ • 表組み • CMS ／アプリのページ • 1：2、左が画像、右が説明 • 見出しを必ずつける 03 整理するためのポイント

Slide 41

Slide 41 text

目次見出し1 　画像　説明見出し2 　画像　説明見出し3 　画像　説明 03 整理するためのポイント

Slide 42

Slide 42 text

03 整理するためのポイント

Slide 43

Slide 43 text

03 整理するためのポイント

Slide 44

Slide 44 text

情報を探すスタンプカード • スタンプカード：基本情報・注意事項 • スタンプカード：CMS「カード登録」 • スタンプカード：CMS「スタンプ登録」 • スタンプカード：CMS「設定」 • スタンプカード：アプリスタンプカードのアプリの〇〇を知りたいから 03 整理するためのポイント

Slide 45

Slide 45 text

慣れると推測しやすくなるアプリのページのあの辺りかなスタンプカード • スタンプカード：基本情報・注意事項 • スタンプカード：CMS「カード登録」 • スタンプカード：CMS「スタンプ登録」 • スタンプカード：CMS「設定」 • スタンプカード：アプリ 03 整理するためのポイント

Slide 46

Slide 46 text

Slide 47

Slide 47 text

整理するためのポイント 1 . 場所とカテゴリー 2 . タイトルの具体化 3 . レイアウトと見出し 03 整理するためのポイント

Slide 48

Slide 48 text

更新のしやすさは 3つのポイントに含まれている 03 整理するためのポイント

Slide 49

Slide 49 text

必要な情報に簡単にアクセスできないことが更新できない要因の1つ 03 整理するためのポイント

Slide 50

Slide 50 text

情報を探す人はだれか • 情報を知りたい人 • 情報をまとめる人 💡 03 整理するためのポイント

Slide 51

Slide 51 text

まとめる側もアクセスしやすいスタンプカード • スタンプカード：基本情報・注意事項 • スタンプカード：CMS「カード登録」 • スタンプカード：CMS「スタンプ登録」 • スタンプカード：CMS「設定」 • スタンプカード：アプリ 03 整理するためのポイント

Slide 52

Slide 52 text

課題をすべておさえた • ドキュメントがどこにあるのかわからない • 似た名前・内容のドキュメントが存在する • ページのどこに書いてあるかわかりづらい • 更新されず内容が最新かわからない 03 整理するためのポイント

Slide 53

Slide 53 text

ここから実際に情報整理を進めていく 03 整理するためのポイント

Slide 54

Slide 54 text

04 まとめ

Slide 55

Slide 55 text

まとめ今回の内容 • テクニカルライターは何をしているのか（簡単に） • 情報をまとめるͨΊͷߟ͔͑ͨʢYappliの仕様書整備を例に） 04 まとめ • 開発現場が抱えるドキュメントの課題 • 解決のため何を実現すればいいのか • 必要な情報に簡単にアクセスできるようにする • 更新しやすい状態とする • 実現のためのポイント