非同期な開発体制を支える ドキュメント文化 YAPC::Hiroshima 2024 2024.02.10 Presented by Ryosuke Yabuki a.k.a Konboi

自己紹介 ▶ 矢吹 遼介 (Ryosuke Yabuki) ▶ Senior Software Engineer (Launchable, Inc.) ▶ 福島県在住 ▶ SNS ▶ blog: https://blog.konboi.com ▶ Github / X(twitter) /Bluesky Konboi 2 2

Launchableについて 3 ▶ Kohsuke Kawaguchi (Jenkins の作者) Harpreet Singh (元Atlassian BitbucketのGM) ▶ Predictive Test Selection / Test Triage / Insight etc ▶ https://www.launchableinc.com/ ▶ テストにまつわる困り事を蓄積したデータを使って 解決するSaaSを開発/運用 ▶ 昨年のYAPC::Kyoto 2023で提供しているCLIツールの話を紹介 ▶ 様々な環境へコマンドラインツールを提供する上での苦労とその対策

ご報告 4 ▶ Python3.5のサポートを切れました🎉 (YAPC::Kyoto 2023の発表より)

WHAT YOU LIKE / お好み 5 ▶ 自分も以前は”ドキュメント”に苦手意識があった。 今はドキュメント書かずに仕事を進められるイメージが沸かない ▶ リモートワークのTipsでドキュメントの話が出るけど具体例は少ない ▶ 自分達のドキュメントの”お好み”を紹介 ▶ 他の会社の例も今後出てくると...うれしい

DISCLAIMER 6 ▶ 本発表で紹介するドキュメントは 詳細設計書, API ドキュメント, 提供ツールの説明書 のようなものではありません Design Doc や Architectural Decision Record (ADR) に近い ▶ LaunchableではConfluence (by Atlassian) を利用 ▶ 発表内では以下のように扱います ▶ ドキュメント: 書かれた文章。Confluenceのページ。 ▶ ドキュメンテーション: ドキュメント(ページ)を書く行為。

アジェンダ 7 ▶ なぜドキュメンテーションを大事にしているのか ▶ どんなドキュメントを運用しているのか ▶ ドキュメント文化の醸造 ▶ まとめ ▶ Q&A

なぜドキュメンテーションを 大事にしているのか 8

なぜドキュメンテーションを大事にしているのか 9 ▶ 組織的な話 ▶ ドキュメントの力

組織的な話 10 ▶ 時差 ▶ 日本とアメリカ西海岸 17時間 / 東海岸 14時間 ▶ 被っているのが日本の午前、アメリカの夕方 ▶ それ以外の時間帯はMTGの調整が難しい ▶ チャットも非同期に議論するには向いていない ▶ 言語 ▶ 英語でのリアルタイムコミュニケーションは正直まだスキルが...

組織的な話 11 ▶ ドキュメントを介してコミュニケーションすることで ▶ 1回のやりとりにより多くの情報を詰め込める ▶ ツールに頼れる ▶ ChatGPT, DeepL, grammarly etc ▶ MTGはデモとか同期的に行うもに時間が割ける

ドキュメントの力 12 ▶ 時間を節約できる ▶ ドキュメンテーションのコストはあるが、 1度書いてしまえば継続して利用できる ▶ MTGのコストが減る。関係者が多ければ尚更 ▶ スケジューリングコスト, 参加のコスト, etc ▶ MTGを最後の手段に出来る ▶ 1:NのNが多ければ多いドキュメントほど効果が高くなる

ドキュメントの力 13 ▶ 書くプロセスを通してより深く考えられる ▶ 書く過程で構成、論理など考えが洗練されていく ▶ 読み手も何度も読み直すことが出来るので理解を深められる

ドキュメントの力 14 ▶ フィードバック(FB)が深く/平等にできる ▶ さまざまな高度でFBできる ▶ 方向性自体, ニュアンス, etc ▶ FBの理解に時間をかけられる ▶ FBを受けた直後だと感情的になりやすい ▶ 話すのが苦手な人でも平等にFBできる ▶ MTG中だと話すのが得意な人が意見しがち ▶ FBする側/される側も比較的すぐに反応する必要がある

どんなドキュメントを 運用しているのか 15

運用しているドキュメントの一覧 (一部) 16 ▶ Project Proposal ▶ DACI (Driver, Approver, Contributor, Informed) ▶ Postmortem ▶ CS Investigation Log ▶ etc

Project Proposal 17 ▶ 新機能の提案, 仕様の変更, etc 各プロジェクト/機能改修のスタート地点 まずこれを書くことからはじまる

Project Proposal 18 ▶ 例:Android CTS Profileの新規開発 ▶ 誰がいつ提案したのか ▶ 誰が担当して、いつ終わったのか

Project Proposal 19 ▶ Why プロダクトチーム以外に向けての概要 ▶ Priority Art 関連資料/プロジェクト ▶ What プロダクトチーム向けの概要 ▶ How どう進めるかの詳細

Project Proposal 20 ▶ PdM, エンジニア 職種関係なく書く ▶ MTGなどで議論が長くなると「一旦One Page書いて整理しますか」 というのは社内でよく見る光景

DACI 21 ▶ 比較的重要な意思決定をするときに書いている ▶ DACI (Driver, Approver, Contributor, Informed) ▶ 誰でも提案に対して意見は言って良い が、意思決定する人は決まっている ▶ 背景や関連するデータ、何を決めたいのかを書く

DACI 22 ▶ 影響度 ▶ 誰が進めるのか ▶ 承認者 ▶ 作業する人 ▶ 承認者ではない 関係者

DACI 23 ▶ 関連するデータ ▶ 進める背景 ▶ オプション ▶ 実行するためのTODO

Postmortem 24 ▶ 障害が起こった際に書く ▶ 障害時/障害対応後にどのような対応を行ったのかを記録 ▶ 後日MTGで発生した原因について振り返りを行い、アクションリストを作成 ▶ アクションリストの担当などもこのドキュメント上で管理

Postmortem 25 ▶ 一部抜粋 ▶ ステータス ▶ 対応済み / 継続中 など ▶ 何が起こったのか どんな対応をしたのか時系列で

Postmortem 26 ▶ MTGにて ▶ 問題のリストアップ ▶ 犯人探しはしない

Postmortem 27 ▶ アクションリストを 日付 + 担当者付きで作成 ▶ 定例で進捗を確認

CS Investigation Log 28 ▶ CS担当と調査担当のエンジニアがコミュニケーションする際に使用 ▶ CS担当がJiraに起票し、該当のページを作成 ▶ エンジニアがどのような調査/対応を行ったのかを記録 ▶ 過去にどのような問い合わせがあったのか。 どのように対応したのかを記録している

CS Investigation Log 29 ▶ CSが用意 ▶ どんな問い合わせか ▶ 何を解決して欲しいか

CS Investigation Log 30 ▶ 追記していく ▶ 原因 ▶ 伝えて欲しいこと ▶ 調査の進捗共有 ▶ etc ▶ ナレッジシェア

どう運用しているの？ 31

どう運用しているのか？ 32 ▶ ドキュメント書くの大変そう ▶ ドキュメント見つからない問題 ▶ とかとか

ドキュメント文化の醸造 33

ドキュメント文化の醸造 34 ▶ 仕事以外もドキュメント ▶ 箱 ▶ 型

仕事以外もドキュメント 35 ▶ 入社のオンボーディングで自己紹介ページを書く ▶ Rocket Fuel Day: 月1回のリフレッシュDay ▶ やったこと無い事をやってみよう (e.g. 家でパンを焼いてみる) ▶ 探検家になろう (e.g. 最寄りの沿線で降りた事の無い駅で降りてみる) ▶ 思い出の食事 (e.g. 遠距離恋愛中の新幹線で食べるお弁当) ▶ ハードルの低い書く機会が多い ▶ “書く” ということに慣れる場が用意されている

箱 36 ▶ ドキュメントを置く場所 ▶ Launchableでは部門ごとにConluenceのスペースが分かれている ▶ オーナーが明確 ▶ Investigation Log は１年経つとアーカイブしてる ▶ アーカイブ !=削除。検索や一覧に出ないがページとしては存在

箱 37

箱 38 Project Proposal置き場 CS Investigation Log置き場

型 39 ▶ ドキュメントの型(フォーマット） ▶ 紹介したドキュメントのように 書く項目が予め決まっている ▶ 何を書けば(埋めれば)いいのか明確 ▶ 読む側も把握しやすい

型 40 ▶ フィードバック(FB)の型(フォーマット) ▶ 30/60/90% FB refs: Trello ▶ 各フェーズに合わせた適切なFBをしましょう ▶ 30%: コンセプトレベル/課題の定義。やる/やらないの決定 ▶ 60%: 課題解決の手段に対してのFB。より洗練するのか？代替案は?? ▶ 90%: 最後の微調整。文言修正とか。

型 41 ▶ 意見 / 提案 / 委任 ( Opinion, a strong suggestion, or a mandate? ) ▶ FBの度合いを明確にする ▶ 個人的な意見 / 変えて欲しい / 参考までに なのか ▶ FBを受け取る方もどの程度反映しないといけないのか理解しやすい

型 42 ▶ 型があることで ▶ いつ/どのように FBすればいいのかする側/受ける側 もわかりやすい ▶ 多少間違っていても型による補完が効く

まとめ 43 ▶ なぜドキュメントを大事にしているのか ▶ 組織 / ドキュメントの持つ力 の両面から紹介 ▶ どんなドキュメントを書いているのか ▶ Project Proposal, DACI, etc など実例を紹介 ▶ ドキュメント文化の醸造 ▶ 仕事以外にも書く機会がたくさん用意されている ▶ 箱 / 型で書く/読む負担を下げる

44 We’re hiring

Thank you! 45

Q&A 46

おまけ 47 ▶ ドキュメント書くのにどれぐらい時間をかけているのか？ ▶ 簡単なもので数時間~1日 ▶ 大きいプロジェクトなものだと 2,3日 ~ 1週間 ▶ FBや議論が発散すると v2, v3 と書き直すこともある ▶ コード書く割合とドキュメントを書く割合は？ ▶ コード 6.5 : ドキュメント3.5 ▶ 月初はどう進めていくかまとめるのにドキュメントの割合多め

Links 48 ● 様々な環境へコマンドラインツールを提供する上での苦労とその対策 / YAPC::Kyoto 2023 https://speakerdeck.com/konboi/yapc-kyoto-2023 ● エンジニアリング x US 海外とのコラボレーション https://speakerdeck.com/yoshiori/enziniaringu-x-us-hai-wai-tofalsekoraboresiyon ● Writing is Thinking https://medium.learningbyshipping.com/writing-is-thinking-an-annotated-twitter-thread- 2a75fe07fade ● Avoid the seagull effect: the 30/60/90 framework for feedback https://www.atlassian.com/blog/productivity/avoid-the-seagull-effect-30-60-90-feedba ck-framework ● Avoiding the Unintended Consequences of Casual Feedback https://www.linkedin.com/pulse/20140602024642-22330283-avoiding-the-unintended- consequences-of-casual-feedback/