InnerSource Pattern: ベース・ドキュメンテーション

概要
パターンの著者: Isabel Drost-Fromm
スピーカー/翻訳: Yuki Hattori | LinkedIn | Twitter | GitHub
YouTube: ベース・ドキュメンテーション
Docs: ベース・ドキュメンテーション

「InnerSource Pattern: ベース・ドキュメンテーション」
インナーソースプロジェクトへの新しいコントリビューターは、誰がプロジェクトを維持し、何に取り組み、どのようにコントリビューションすればよいかを理解するのに苦労しています。`README.md`/`CONTRIBUTING.md` のような標準ファイルでドキュメントを提供することで、新しいコントリビューターのためのセルフサービスなプロセスを可能にし、よくある質問に対する答えを自分自身で見つけることができるようにします。

リンク
InnerSource Patterns: English 🇬🇧| 日本語 🇯🇵
Website: innersourcecommons.org
Slack: Invite Link | 🇯🇵#jp-general
Twitter: @InnerSourceJP (日本) | @InnerSourceOrg (公式)

Transcript

1. ベース・ドキュメンテーション
   InnerSource Patterns
   Speaker: Yuki Hattori (@yuhattor)
   Pattern Author: Isabel Drost-Fromm
   

   View Slide

2. 概要
   インナーソースプロジェクトへの新しいコントリビューターは、誰がプロジェクトを維持し、何に取り組
   み、どのようにコントリビューションすればよいかを理解するのに苦労しています。
   README.md / CONTRIBUTING.md
   のような標準ファイルでドキュメントを提供することで、新しいコントリビ
   ューターのためのセルフサービスなプロセスを可能にし、よくある質問に対する答えを自分自身で見つける
   ことができるようにします。
   InnerSource Patterns:
   ベース・ドキュメンテーション
   @yuhattor
   2
   

   View Slide

3. 問題
   あるチームは、新しく始めたプロジェクトや既存のプロジェクトをより広い組織で共有し、それに対するコ
   ントリビューションを受けたいと考えています。潜在的なコントリビューターは、しばしば迷ってしまいま
   す。チームの好ましいコミュニケーションチャネルを特定できない。新しい機能が追加されることに意味が
   あるのかどうか、すぐに判断することはできません。また現在、どの同僚が活発にプロジェクトをメンテナ
   ンスしているのかを正確に理解するのに苦労しています。
   InnerSource Patterns:
   ベース・ドキュメンテーション
   @yuhattor
   3
   

   View Slide

4. 状況
   プロジェクトは、インナーソースプロジェクトとして他の人と共有されることになります。他の人がプロジ
   ェクトが何であるか、また、どのようにコントリビュートするかを理解できるようにするために、プロジェ
   クトはいくつかの基本的なレベルのドキュメントを提供する必要があります。これまでのところ、プロジェ
   クトは、すべてのドキュメントまたはユーザーがセルフサービス方式でそれを試してみるだけでなく、コン
   トリビューターが迅速にスピードアップするために必要な項目がいくつか不足しています。
   InnerSource Patterns:
   ベース・ドキュメンテーション
   @yuhattor
   4
   

   View Slide

5. 組織に働く力学
   最近になってプロジェクトがインナーソースプロジェクトになったことに伴い、セルフサービスの文書
   が不足している。
   ホストチームには、インナーソースの経験が限られており、どのような情報を含めるべきか、どこで見
   つけられるようにするべきかがわからない。
   既存のドキュメントは、技術的な側面に対応しているが、コミュニケーションや計画を促進する情報を
   カバーしていない。
   チーム内にある暗黙の知識が書き留められていないため、コントリビューターにも不明。
   ドキュメントが不足していることは、セットアップに時間を要することを意味し、ドキュメントを作成
   するのにも時間がかかる。
   ドキュメントを作成することで、より多くの人がプロジェクトに参加できるようになり、プロジェクト
   はよりスムーズに進む。
   InnerSource Patterns:
   ベース・ドキュメンテーション
   @yuhattor
   5
   

   View Slide

6. ソリューション
   新しいコントリビューターのために、より明確なドキュメント作成の作業に取り組む。このドキュメントを
   作成する際の目標は、よくある質問に標準的なドキュメント形式で回答することで、可能な限りセルフサー
   ビスのプロセスを開始できるようにすることです。
   InnerSource Patterns:
   ベース・ドキュメンテーション
   @yuhattor
   6
   

   View Slide

7. README.md
   まだ存在しない場合は、あなたのプロジェクトの
   README.md
   を作成してください。それには以下の内容が
   含まれていなければなりません。
   プロジェクトのミッション
   プロジェクトで実働をするユーザーに向けた "Getting Started"
   セクション。
   プロジェクトユーザーのための詳細なドキュメント -
   またはそれへのリンク
   プロジェクトを修正するために必要なドキュメント -
   またはそれへのリンク
   プロジェクトにコントリビュートする方法に関するドキュメント -
   またはそれへのリンク
   プロジェクトがどのようなアクセス可能なパブリックもしくはアーカイブのコミュニケーションチャネ
   ルを用いているかを説明する "Getting involved"
   セクション。
   プロジェクトを支える トラステッドコミッターが誰であるかを説明する "Who we are"
   のセクション。
   プロジェクトが貢献者をトラステッドコミッターにするための基準の説明。
   コントリビューターがそのプロジェクトにおけるトラステッドコミッターになるための基準及び、その
   パスが存在するならばそのパス
   InnerSource Patterns:
   ベース・ドキュメンテーション
   @yuhattor
   7
   

   View Slide

8. CONTRIBUTING.md
   コントリビューションを行うための手順の説明が複雑すぎる場合は、
   CONTRIBUTING.md
   というドキュメン
   トを別に作成します。この文書では、コントリビューターが過去によく聞かれた質問に答えるようにしま
   す。前もって包括的なドキュメントを提供する必要はありません。むしろ、コントリビューターが必要とし
   ていることが証明された情報を共有しましょう。おそらく、以下のトピックのうちの1
   つ以上に触れること
   になるでしょう。
   プロジェクトのソースコードをバージョン管理からチェックアウトする方法
   プロジェクトに変更を加える方法 (
   コーディングガイドラインに関する情報を含む可能性があります)
   プロジェクトをビルドする方法
   上記の修正が新しいバグを引き起こしていないことを確認するためのテストの実行方法
   プロジェクトにあなたの修正をサブミットする方法
   修正が行われた場合、変更が取り込まれるまでに必要な所要時間に関する情報
   InnerSource Patterns:
   ベース・ドキュメンテーション
   @yuhattor
   8
   

   View Slide

9. CONTRIBUTING.md
   様々なオープンソースプロジェクトにおいて、README.md
   の書き方
   や、CONTRIBUTING.md
   ファイルにどのような情報を含めるべきか
   についての良い例がたくさんあります
   How to write a readme that rocks
   Open Source Guide from GitHub
   Producing Open Source
   Producing Open Source
   の Getting Started chapter
   には、ホストチームのメ
   ンバー、ユーザー、コントリビューターが必要とするもののかなり広範な
   リストがあります
   このパターンには、すぐに始められるように、2
   つの非常に基本的
   なテンプレートが付属しています
   README-template.md
   CONTRIBUTING-template.md
   InnerSource Patterns:
   ベース・ドキュメンテーション
   @yuhattor
   9
   

   View Slide

10. 結果の状況
    コントリビューターがスピードを上げるまでの時間が大幅に短縮されます
    トラステッドコミッター が初歩の質問に答える時間が大幅に短縮され、他の作業に時間を割くことがで
    きるようになります
    誤った理解や、同じ方向を向いていないことによるエスカレーションが大幅に削減されます
    InnerSource Patterns:
    ベース・ドキュメンテーション
    @yuhattor
    10
    

    View Slide

11. 事例
    Europace AG -
    こちらのブログをご覧ください InnerSource: Adding base documentation
    Paypal Inc.
    InnerSource Patterns:
    ベース・ドキュメンテーション
    @yuhattor
    11
    

    View Slide

12. リファレンス
    README-template.md and
    CONTRIBUTING-template.md
    InnerSource Patterns:
    ベース・ドキュメンテーション
    @yuhattor
    12
    

    View Slide

13. InnerSource
    についてもっと知る
    InnerSource Commons: https://innersourcecommons.org
    Join our Slack community: https://innersourcecommons.org/slack
    InnerSource Patterns: https://patterns.innersourcecommons.org
    Twitter: @InnerSourceOrg
    日本語 Slack
    チャンネル: #jp-general
    日本語 Twitter: @InnerSourceJP
    InnerSource Patterns:
    ベース・ドキュメンテーション
    @yuhattor
    13
    

    View Slide