# 検索可能性の必要性とパッシブドキュメンテーション

**要約**

* パッシブドキュメンテーション\[4-1] は部族内知識の捕捉と人材育成に欠かせないものです。チームは初期にコミュニケーションの落ち込みを感じることがありますが、速度の向上はその落ち込みを補っても余りあるのです。
* ドキュメンテーションの作成者と消費者の両方に報酬を与えることで、パッシブドキュメンテーションを促進できます。
* パッシブドキュメンテーションを利用可能とするためには、それが検索可能な状態でなければなりません。これはサイロ化した複数のデータセットにまたがるタグづけをときどきする必要性を意味しています。

## パッシブドキュメンテーションの作成

パッシブドキュメンテーションは将来のためではなく、現在必要なことを説明するために書かれた情報から成っています。 例えば以下のようなものです。

* トラステッドコミッター (TC) が、コントリビューターに対して、彼らのコードベースを統合する方法を指導する際に行われる会話
* プロダクトオーナーたちが互いにタスクの優先順位を説明したり、整理整頓するときに交わす会話
* コードの一部とプロジェクトのコードに関するストーリー、そしてこれらに関する生きた会話

最初に最も難しいのは、人々に対してこれらの会話をもっとオープンにすることを説得することです。 彼らは今後も参照するドキュメントを事前準備なしに作ることに対して慎重になる傾向があります。 しかし彼らが公式なドキュメントを書いているのではなく、単に育成のために交わした会話を記録しているだけであると気づくと、抵抗感がなくなっていくことがわかりました。 またドキュメンテーションの急速な拡充によるメリットは誰の目にも明らかでした。

パッシブドキュメンテーションに記録されるには、会話は文書上で行われる必要があります。 一般的な記述形式はプルリクエストのコメント、Slack のパブリックチャネルにあるタグ付けされた会話、wiki 内のコメントページ、メーリングリストにあるタグつきメッセージなどです。 オープンソースの世界では、メーリングリスト、もしくは wiki で公開されていない会話は "本物" ではないとよく言われます。 私たちは、社内においても同じような文化へ変化させていこうと取り組んでいます。 また、もし対面で重要な議論があったのであれば、その終わりには必ず誰か一人が記録に残すことを合意します。 そのためには、全ての関係者が承認できるように議論の内容を詳しくメールに記述し、その内容をより大きなコミュニティにも公開します。

## この素晴らしい説明書を読んだかね？

トラステッドコミッターがプルリクエスト上で公開されたいくつかの質問に答えたあと、次のコントリビューターからのプルリクエストの速度がすぐに上昇することがわかりました。

まじめなコントリビューターは助けを求める前に、あるいはプルリクエストを出す前にドキュメンテーションを探します。 私たちの場合、これらのドキュメントはすべて GitHub 上で管理しているのでどこを見ればいいかほとんど迷うことはありません。 また、コントリビューターが過去のアドバイスをプルリクエストに反映していないとき、過去の会話を参照するように差し戻すことをトラステッドコミッターたちにおすすめしています。

私たちは、こうした公開された会話に報いる方法を模索しています。 関連性の高いドキュメントを書いた人がいた場合には、そのことを強調するダッシュボードを作成しています。 また、調査を先に行ったコントリビューターに対して、トラステッドコミッターが報酬を与えることができます。 トラステッドコミッターは、誰がその方向性に従うのかを素早く知り、その人のプルリクエストを優先的に処理することになるでしょう！

## 検索可能性の必要性

オープンソースの世界では、何かをする方法について知りたいとき、単にググれば良いのです。 しかし、企業においては、情報を見つけることがオープンソースの世界と比較すると、はるかに難しいのです。 たいていの情報は様々なソフトウェアやデータストアに保存され、検索可能かどうかもわかりません。 多くの場合でこれらの保存先にある情報は、デフォルトで非公開にした方が安全だと思われがちです。 ですが、長い目で見るとこの状態は企業に大きなダメージを与えることになってしまいます。 情報を閉ざした場合、新しく入社した従業員のオンボーディングは困難なものになり、オンボーディングの際に習得できる知識の統一がほぼ不可能になります。 そのうえ、部族内知識を招く、あるいは助長する雰囲気を生み出しかねません。

時に、これらの問題はツール自身が持つ検索機能が粗悪だったり、そもそも存在しないことにより生じます。 ただ、多くのツールを使用しているので、情報の集約が難しいのです。 また、全てのユーザーがアクセスできるようにするためには、追加で費用がかかることが多く、この問題を悪化させているケースがよくあります。

しかしドキュメントが役に立つのはそれを見つけることができる場合に限られるため、この問題の解決は非常に重要です。 私たちのチームの多くは手動で検索ができるように、サイロ化されたアプリケーションをまたぐようなタグづけを要求し始めています。 たとえば、バグ修正のための JIRA の Issue 番号や、GitHub の機能レベルのプルリクエストに対する Rally のストーリー番号など検索可能なタグが設定されていないプルリクエストは検討対象外とコントリビューション協定で定めているチームもあります。 これは誰かが閉ざされた複数のデータストアをまたいで検索する必要があるときに大きな助けになりますが、理想的な方法ではないですし、開発者たちがかなりまじめであることが求められます。

そこで私たちは情報の発見と共有を手助けするツールの開発を始めました。 それが [RallySlack](https://github.com/paypal/rallyslack) です (オープンソースです！)。 Slack 上で誰かが活動しているとき、RallySlack は自動的にその個人のすべての Rally ストーリーを取り出して、Slack の会話を見つけてタグ付けしやすくします。 RallySlack を使えばユーザーは Rally のストーリー番号を探したり覚えたりする必要がなくなります。 また、現在私たちは GitHub でのプルリクエストや Issue に対して Rally のストーリー番号のタグ付けを手助けする類似のツールを開発しています。 最終的にはこのツールも RallySlack 同様にオープンソース化したいと考えています。

## 4章の参考文献と注釈

* \[4-1] (訳注) ドキュメント(document)が単一の文書を指すのに対し、ドキュメンテーション(documentation)はドキュメントの集合を指します。本章で解説されているように、プルリクエストのコメント、Slack のパブリックチャネルにあるタグ付けされた会話、といった過ぎ行く(パッシブな:passive)文章の集合がパッシブドキュメンテーションです。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://jp-contents.innersourcecommons.org/understanding-the-innersource-checklist/contents/4-passive-documentation-and-the-need-for-findability.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.