OSSのメンテナが 入門ハンズオンを なぜ・どのように作成したか

2024-09-14 DevRel/Japan CONFERENCE 2024での登壇資料です。
https://devrel.tokyo/japan-2024/sessions/e87fbaa0-dff1-4bfb-b29f-6faf618abf56/

※SpeakerDeck用に、フォントを一部調整しています。

Transcript

1. OSSのメンテナが 入門ハンズオンを なぜ・どのように作成したか 2024-09-14 DevRel/Japan Conference 2024 菊池 哲哉 @CyberAgent, Inc.
2. #DevRelJP Software Engineer ◦ 所属: (株)サイバーエージェント ◦ PipeCDのメンテナ ▪ 開発(主にAWS関連) ▪ 社内サポート ▪ 普及活動 菊池 哲哉 Kikuchi Tetsuya @t-kikuc @t_kikuc 2
3. #DevRelJP アジェンダ 1. PipeCD、入門ハンズオンとは？ 2. なぜ作成したか 3. どのように作成したか 4. 公開後の結果、今後やりたいこと 主な対象者： 　　広めたい技術がある方、OSSに携わる方 3
4. 1. PipeCD、 入門ハンズオンとは？ 4
5. #DevRelJP PipeCDとは • オープンソースのCD(継続的デリバリー)ツール • サイバーエージェント発のOSS • 2023年5月〜 CNCF Sandbox Project 沿革詳細: https://speakerdeck.com/ffjlabo/our-journey-from-in-house-cd-system-to-open-source 5
6. #DevRelJP なぜPipeCDを普及させたい？ 6 より多くのユーザ よりよいプロダクト 社内の生産性向上
7. #DevRelJP PipeCD入門ハンズオンとは • PipeCDの構築からデプロイまでを試せる ◦ 公開： 2024年5月 ◦ 言語： 英語・日本語 ◦ 所要時間： 30分~1時間ほど https://github.com/pipe-cd/tutorial/blob/main/content/ja/README.md 7
8. #DevRelJP PipeCD入門ハンズオンとは 8
9. 2. なぜ作成したか 9
10. A. 入門コストを下げて、ユーザを増やすため 10 10
11. Q. なぜ [入門] [ハンズオン] を [今] 作成したか 11 11
12. 　　A. 1. 入門コストが高かった 2. 他のアクションよりも重要だった 3. 手段はハンズオン形式が適切だった 12 12
13. #DevRelJP 1. 入門コストが高かった • 「PipeCD興味あるけど、まだ触ったことない」　という 声をよく聞いていた • 一因： 入門コストが高い ◦ セットアップが大変 ◦ どこから入門すればよいかわかりにくい 13
14. #DevRelJP 2. 他の施策より重要だった • 他にもやりたいことは多数 ◦ メディア、イベント露出を増やす ◦ 他ツールからの移行を容易に ◦ 本番構築コストを下げる ◦ コントリビューションを簡単に ◦ 情報量(プラクティス等)の拡充 　　　　・・・ 14
15. #DevRelJP 2. 他の施策より重要だった • 他にもやりたいことは多数 ◦ メディア、イベント露出を増やす ◦ 他ツールからの移行を容易に ◦ 本番構築コストを下げる ◦ コントリビューションを簡単に ◦ 情報量(プラクティス等)の拡充 　　　　・・・ 15 ユーザ数 情報量 開発者数
16. #DevRelJP 2. 他の施策より重要だった • ユーザ数は命 ◦ 情報量やコントリビュータ数の源泉 • コントリビュータを増やすのは難しい 16
17. #DevRelJP 2. 他の施策より重要だった 17 認知している人 触ったことがある人 検証している人 本番ユーザ まだ認知していない人
18. #DevRelJP 2. 他の施策より重要だった 18 認知している人 触ったことがある人 検証している人 本番ユーザ まだ認知していない人 メディア、イベント露出 他ツールからの移行を容易に 本番構築コストを下げる 入門コストを下げる アクション例
19. #DevRelJP 2. 他の施策より重要だった • まとめ ◦ まずユーザ数を増やしたい ◦ 入門がボトルネック 19
20. #DevRelJP 3. なぜハンズオン形式か • 動かせばイメージを掴める • 丁寧に伝えられる ◦ 公式リファレンスは基本的に入門者向けではない • スケールする ◦ 個別教育やイベントはメンテナがボトルネックに 20
21. #DevRelJP 3. なぜハンズオン形式か • 簡易的なリンク集を作成 ◦ 👍「とりあえずコレ見て」 ◦ 😕 各ページがやさしくない 21
22. 3. どのように作成したか 22
23. #DevRelJP 作成の流れ 1. 参考資料にあたる 2. 前提知識とゴールの設定 [最重要] 3. 執筆 4. 動作検証 5. 英語版公開 +α 日本語版作成・公開 23 約1ヶ月
24. #DevRelJP 1/5. 参考資料にあたる • 他のOSSのチュートリアル ◦ 特に構成・量・公開方法など • ドキュメントライティングの書籍 ◦ chap.1「読み手の理解」は必見 https://amzn.asia/d/8QigkRD 24
25. #DevRelJP 2/5. 前提知識とゴールの設定 25
26. #DevRelJP 2/5. 前提知識とゴールの設定 • なぜ必要か？ ◦ 読者が Not for me かをすぐに判断できる ◦ 説明の取捨選択の判断基準になる ▪ 読者： 情報過不足はストレス ▪ 筆者： 書くか書かないか迷うのは無駄 26
27. #DevRelJP 2/5. 前提知識とゴールの設定 • ゴールの設定 「PipeCDを触ったことある人」とは？ 　 27 ✅ゴールとすること • 簡易的に構築する • 最低限の機能を動かす • 最低限の仕組みを理解する ☑ゴールとしないこと • 本番向けの構築 • 様々な機能を使う • 網羅的な理解 • PipeCD自体の開発
28. #DevRelJP 2/5. 前提知識とゴールの設定 • 前提知識の設定 「PipeCD/入門ハンズオンに興味を持つ人」とは？ 　 28 ✅前提とする知識 • PipeCDとは何か • Git,CI/CDの基礎 • K8s/CloudRun/Terraform/ ECS/Lambdaのいずれか ☑前提としない知識 • PipeCDの各種用語 • PipeCDの仕組み
29. #DevRelJP 3/5. 執筆 つまずき=離脱を防ぐ • 手間を減らす: 前提条件、作業ステップ数 • 説明を減らす: 前提知識・ゴールに基づいて取捨選択 ◦ 図も入門者向けに新作 • 「知識の呪い」に注意 ◦ 知識の呪い： 「自分が知っていることは 相手も知っている」と誤認すること ◦ 対処法： 入門者にヒアリング 29
30. #DevRelJP 4/5. 動作検証 • 確実に動作するまで修正 • トラブルシューティングも追加 30
31. #DevRelJP 5/5. 英語版公開 • GitHubで公開 ◦ Webサイトのホストはメンテが手間 • 公式ドキュメントとは別リポジトリで作成 ◦ 厳密なレビューは不要 ◦ 必ずしも最新に追従する必要はない 31
32. #DevRelJP +α. 日本語版も作成・公開 • メンテコストを観察してから実行した ◦ 5月末 英語版公開 → 8月上旬 日本語版公開 • 翻訳作業は1日で完結 ◦ そもそもボリュームを減らしていた ◦ 画像とCodeは日英で共通 32
33. 4. 公開後の結果、 今後やりたいこと 33
34. #DevRelJP 結果 • 定量面（GitHub Insights） ◦ unique visitor: のべ350人ほど ◦ unique cloner: のべ70人ほど ▪ ≒ハンズオンをやってみた人数 ◦ 英語版/日本語版公開日やイベント参加日に増加 • 定性面 ◦ 「入門で挫折」を恐れずに認知拡大へ 34
35. #DevRelJP 今後やりたいこと • 品質・効果測定 ◦ コンテンツの質（完走率、所要時間など） ◦ 目的の達成度（どう測る？） • プロダクト自体の改良による、作業の簡略化 • 「PipeCDを触ったことがある人」を 　 「PipeCDを検証する人」に引き上げる 35
36. Takeaway 36
37. #DevRelJP Takeaway • 入門ハンズオンで「興味持った人」を 「触ったことある人」に • ボリュームは減らす ◦ 前提知識とゴールの設定が効果的 ◦ ローカライズもしやすくなる • ユーザヒアリングでつまずきポイントを知る 37
38. #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
39. 日本語版Tutorial🎉