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

非同期開発体制を支えるドキュメント文化 / YAPC::Hiroshima 2024

Konboi
February 10, 2024
9.3k

非同期開発体制を支えるドキュメント文化 / YAPC::Hiroshima 2024

Konboi

February 10, 2024
Tweet

Transcript

  1. 自己紹介 ▶ 矢吹 遼介 (Ryosuke Yabuki) ▶ Senior Software Engineer

    (Launchable, Inc.) ▶ 福島県在住 ▶ SNS ▶ blog: https://blog.konboi.com ▶ Github / X(twitter) /Bluesky Konboi 2 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ツールの話を紹介 ▶ 様々な環境へコマンドラインツールを提供する上での苦労とその対策
  3. WHAT YOU LIKE / お好み 5 ▶ 自分も以前は”ドキュメント”に苦手意識があった。 今はドキュメント書かずに仕事を進められるイメージが沸かない ▶

    リモートワークのTipsでドキュメントの話が出るけど具体例は少ない ▶ 自分達のドキュメントの”お好み”を紹介 ▶ 他の会社の例も今後出てくると...うれしい
  4. DISCLAIMER 6 ▶ 本発表で紹介するドキュメントは 詳細設計書, API ドキュメント, 提供ツールの説明書 のようなものではありません Design

    Doc や Architectural Decision Record (ADR) に近い ▶ LaunchableではConfluence (by Atlassian) を利用 ▶ 発表内では以下のように扱います ▶ ドキュメント: 書かれた文章。Confluenceのページ。 ▶ ドキュメンテーション: ドキュメント(ページ)を書く行為。
  5. 組織的な話 10 ▶ 時差 ▶ 日本とアメリカ西海岸 17時間 / 東海岸 14時間

    ▶ 被っているのが日本の午前、アメリカの夕方 ▶ それ以外の時間帯はMTGの調整が難しい ▶ チャットも非同期に議論するには向いていない ▶ 言語 ▶ 英語でのリアルタイムコミュニケーションは正直まだスキルが...
  6. ドキュメントの力 12 ▶ 時間を節約できる ▶ ドキュメンテーションのコストはあるが、 1度書いてしまえば継続して利用できる ▶ MTGのコストが減る。関係者が多ければ尚更 ▶

    スケジューリングコスト, 参加のコスト, etc ▶ MTGを最後の手段に出来る ▶ 1:NのNが多ければ多いドキュメントほど効果が高くなる
  7. ドキュメントの力 14 ▶ フィードバック(FB)が深く/平等にできる ▶ さまざまな高度でFBできる ▶ 方向性自体, ニュアンス, etc

    ▶ FBの理解に時間をかけられる ▶ FBを受けた直後だと感情的になりやすい ▶ 話すのが苦手な人でも平等にFBできる ▶ MTG中だと話すのが得意な人が意見しがち ▶ FBする側/される側も比較的すぐに反応する必要がある
  8. 運用しているドキュメントの一覧 (一部) 16 ▶ Project Proposal ▶ DACI (Driver, Approver,

    Contributor, Informed) ▶ Postmortem ▶ CS Investigation Log ▶ etc
  9. Project Proposal 19 ▶ Why プロダクトチーム以外に向けての概要 ▶ Priority Art 関連資料/プロジェクト

    ▶ What プロダクトチーム向けの概要 ▶ How どう進めるかの詳細
  10. DACI 21 ▶ 比較的重要な意思決定をするときに書いている ▶ DACI (Driver, Approver, Contributor, Informed)

    ▶ 誰でも提案に対して意見は言って良い が、意思決定する人は決まっている ▶ 背景や関連するデータ、何を決めたいのかを書く
  11. Postmortem 25 ▶ 一部抜粋 ▶ ステータス ▶ 対応済み / 継続中

    など ▶ 何が起こったのか どんな対応をしたのか時系列で
  12. CS Investigation Log 30 ▶ 追記していく ▶ 原因 ▶ 伝えて欲しいこと

    ▶ 調査の進捗共有 ▶ etc ▶ ナレッジシェア
  13. 仕事以外もドキュメント 35 ▶ 入社のオンボーディングで自己紹介ページを書く ▶ Rocket Fuel Day: 月1回のリフレッシュDay ▶

    やったこと無い事をやってみよう (e.g. 家でパンを焼いてみる) ▶ 探検家になろう (e.g. 最寄りの沿線で降りた事の無い駅で降りてみる) ▶ 思い出の食事 (e.g. 遠距離恋愛中の新幹線で食べるお弁当) ▶ ハードルの低い書く機会が多い ▶ “書く” ということに慣れる場が用意されている
  14. 箱 36 ▶ ドキュメントを置く場所 ▶ Launchableでは部門ごとにConluenceのスペースが分かれている ▶ オーナーが明確 ▶ Investigation

    Log は1年経つとアーカイブしてる ▶ アーカイブ !=削除。検索や一覧に出ないがページとしては存在
  15. 型 40 ▶ フィードバック(FB)の型(フォーマット) ▶ 30/60/90% FB refs: Trello ▶

    各フェーズに合わせた適切なFBをしましょう ▶ 30%: コンセプトレベル/課題の定義。やる/やらないの決定 ▶ 60%: 課題解決の手段に対してのFB。より洗練するのか?代替案は?? ▶ 90%: 最後の微調整。文言修正とか。
  16. 型 41 ▶ 意見 / 提案 / 委任 ( Opinion,

    a strong suggestion, or a mandate? ) ▶ FBの度合いを明確にする ▶ 個人的な意見 / 変えて欲しい / 参考までに なのか ▶ FBを受け取る方もどの程度反映しないといけないのか理解しやすい
  17. まとめ 43 ▶ なぜドキュメントを大事にしているのか ▶ 組織 / ドキュメントの持つ力 の両面から紹介 ▶

    どんなドキュメントを書いているのか ▶ Project Proposal, DACI, etc など実例を紹介 ▶ ドキュメント文化の醸造 ▶ 仕事以外にも書く機会がたくさん用意されている ▶ 箱 / 型で書く/読む負担を下げる
  18. おまけ 47 ▶ ドキュメント書くのにどれぐらい時間をかけているのか? ▶ 簡単なもので数時間~1日 ▶ 大きいプロジェクトなものだと 2,3日 ~

    1週間 ▶ FBや議論が発散すると v2, v3 と書き直すこともある ▶ コード書く割合とドキュメントを書く割合は? ▶ コード 6.5 : ドキュメント3.5 ▶ 月初はどう進めていくかまとめるのにドキュメントの割合多め
  19. 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/