OSSのメンテナが 入門ハンズオンを なぜ・どのように作成したか 2024-09-14 DevRel/Japan Conference 2024 菊池 哲哉 @CyberAgent, Inc.

#DevRelJP Software Engineer ○ 所属: (株)サイバーエージェント ○ PipeCDのメンテナ ■ 開発(主にAWS関連) ■ 社内サポート ■ 普及活動 菊池 哲哉 Kikuchi Tetsuya @t-kikuc @t_kikuc 2

#DevRelJP アジェンダ 1. PipeCD、入門ハンズオンとは？ 2. なぜ作成したか 3. どのように作成したか 4. 公開後の結果、今後やりたいこと 主な対象者： 　　広めたい技術がある方、OSSに携わる方 3

1. PipeCD、 入門ハンズオンとは？ 4

#DevRelJP PipeCDとは ● オープンソースのCD(継続的デリバリー)ツール ● サイバーエージェント発のOSS ● 2023年5月〜 CNCF Sandbox Project 沿革詳細: https://speakerdeck.com/ffjlabo/our-journey-from-in-house-cd-system-to-open-source 5

#DevRelJP なぜPipeCDを普及させたい？ 6 より多くのユーザ よりよいプロダクト 社内の生産性向上

#DevRelJP PipeCD入門ハンズオンとは ● PipeCDの構築からデプロイまでを試せる ○ 公開： 2024年5月 ○ 言語： 英語・日本語 ○ 所要時間： 30分~1時間ほど https://github.com/pipe-cd/tutorial/blob/main/content/ja/README.md 7

#DevRelJP PipeCD入門ハンズオンとは 8

2. なぜ作成したか 9

A. 入門コストを下げて、ユーザを増やすため 10 10

Q. なぜ [入門] [ハンズオン] を [今] 作成したか 11 11

　　A. 1. 入門コストが高かった 2. 他のアクションよりも重要だった 3. 手段はハンズオン形式が適切だった 12 12

#DevRelJP 1. 入門コストが高かった ● 「PipeCD興味あるけど、まだ触ったことない」　という 声をよく聞いていた ● 一因： 入門コストが高い ○ セットアップが大変 ○ どこから入門すればよいかわかりにくい 13

#DevRelJP 2. 他の施策より重要だった ● 他にもやりたいことは多数 ○ メディア、イベント露出を増やす ○ 他ツールからの移行を容易に ○ 本番構築コストを下げる ○ コントリビューションを簡単に ○ 情報量(プラクティス等)の拡充 　　　　・・・ 14

#DevRelJP 2. 他の施策より重要だった ● 他にもやりたいことは多数 ○ メディア、イベント露出を増やす ○ 他ツールからの移行を容易に ○ 本番構築コストを下げる ○ コントリビューションを簡単に ○ 情報量(プラクティス等)の拡充 　　　　・・・ 15 ユーザ数 情報量 開発者数

#DevRelJP 2. 他の施策より重要だった ● ユーザ数は命 ○ 情報量やコントリビュータ数の源泉 ● コントリビュータを増やすのは難しい 16

#DevRelJP 2. 他の施策より重要だった 17 認知している人 触ったことがある人 検証している人 本番ユーザ まだ認知していない人

#DevRelJP 2. 他の施策より重要だった 18 認知している人 触ったことがある人 検証している人 本番ユーザ まだ認知していない人 メディア、イベント露出 他ツールからの移行を容易に 本番構築コストを下げる 入門コストを下げる アクション例

#DevRelJP 2. 他の施策より重要だった ● まとめ ○ まずユーザ数を増やしたい ○ 入門がボトルネック 19

#DevRelJP 3. なぜハンズオン形式か ● 動かせばイメージを掴める ● 丁寧に伝えられる ○ 公式リファレンスは基本的に入門者向けではない ● スケールする ○ 個別教育やイベントはメンテナがボトルネックに 20

#DevRelJP 3. なぜハンズオン形式か ● 簡易的なリンク集を作成 ○ 👍「とりあえずコレ見て」 ○ 😕 各ページがやさしくない 21

3. どのように作成したか 22

#DevRelJP 作成の流れ 1. 参考資料にあたる 2. 前提知識とゴールの設定 [最重要] 3. 執筆 4. 動作検証 5. 英語版公開 +α 日本語版作成・公開 23 約1ヶ月

#DevRelJP 1/5. 参考資料にあたる ● 他のOSSのチュートリアル ○ 特に構成・量・公開方法など ● ドキュメントライティングの書籍 ○ chap.1「読み手の理解」は必見 https://amzn.asia/d/8QigkRD 24

#DevRelJP 2/5. 前提知識とゴールの設定 25

#DevRelJP 2/5. 前提知識とゴールの設定 ● なぜ必要か？ ○ 読者が Not for me かをすぐに判断できる ○ 説明の取捨選択の判断基準になる ■ 読者： 情報過不足はストレス ■ 筆者： 書くか書かないか迷うのは無駄 26

#DevRelJP 2/5. 前提知識とゴールの設定 ● ゴールの設定 「PipeCDを触ったことある人」とは？ 　 27 ✅ゴールとすること ● 簡易的に構築する ● 最低限の機能を動かす ● 最低限の仕組みを理解する ☑ゴールとしないこと ● 本番向けの構築 ● 様々な機能を使う ● 網羅的な理解 ● PipeCD自体の開発

#DevRelJP 2/5. 前提知識とゴールの設定 ● 前提知識の設定 「PipeCD/入門ハンズオンに興味を持つ人」とは？ 　 28 ✅前提とする知識 ● PipeCDとは何か ● Git,CI/CDの基礎 ● K8s/CloudRun/Terraform/ ECS/Lambdaのいずれか ☑前提としない知識 ● PipeCDの各種用語 ● PipeCDの仕組み

#DevRelJP 3/5. 執筆 つまずき=離脱を防ぐ ● 手間を減らす: 前提条件、作業ステップ数 ● 説明を減らす: 前提知識・ゴールに基づいて取捨選択 ○ 図も入門者向けに新作 ● 「知識の呪い」に注意 ○ 知識の呪い： 「自分が知っていることは 相手も知っている」と誤認すること ○ 対処法： 入門者にヒアリング 29

#DevRelJP 4/5. 動作検証 ● 確実に動作するまで修正 ● トラブルシューティングも追加 30

#DevRelJP 5/5. 英語版公開 ● GitHubで公開 ○ Webサイトのホストはメンテが手間 ● 公式ドキュメントとは別リポジトリで作成 ○ 厳密なレビューは不要 ○ 必ずしも最新に追従する必要はない 31

#DevRelJP +α. 日本語版も作成・公開 ● メンテコストを観察してから実行した ○ 5月末 英語版公開 → 8月上旬 日本語版公開 ● 翻訳作業は1日で完結 ○ そもそもボリュームを減らしていた ○ 画像とCodeは日英で共通 32

4. 公開後の結果、 今後やりたいこと 33

#DevRelJP 結果 ● 定量面（GitHub Insights） ○ unique visitor: のべ350人ほど ○ unique cloner: のべ70人ほど ■ ≒ハンズオンをやってみた人数 ○ 英語版/日本語版公開日やイベント参加日に増加 ● 定性面 ○ 「入門で挫折」を恐れずに認知拡大へ 34

#DevRelJP 今後やりたいこと ● 品質・効果測定 ○ コンテンツの質（完走率、所要時間など） ○ 目的の達成度（どう測る？） ● プロダクト自体の改良による、作業の簡略化 ● 「PipeCDを触ったことがある人」を 　 「PipeCDを検証する人」に引き上げる 35

Takeaway 36

#DevRelJP Takeaway ● 入門ハンズオンで「興味持った人」を 「触ったことある人」に ● ボリュームは減らす ○ 前提知識とゴールの設定が効果的 ○ ローカライズもしやすくなる ● ユーザヒアリングでつまずきポイントを知る 37

#DevRelJP 参考・関連資料 ● PipeCD公式サイト https://pipecd.dev/ ● (PipeCDの沿革) Our Journey from In-House CD System to Open Source https://speakerdeck.com/ffjlabo/our-journey-from-in-house-cd-system-to-open-source ● The AAARRRP Developer Relations Strategy Framework https://www.leggetter.co.uk/aaarrrp/ ● Kubernetes Tutorial https://kubernetes.io/ja/docs/tutorials/ ● 『エンジニアのためのドキュメントライティング』 https://amzn.asia/d/8QigkRD ● 『DevRelの教科書』 https://amzn.asia/d/dkqVmkL 38

日本語版Tutorial🎉