# ドキュメントのAI可読性

現在、GitHub CopilotというAI補完機能を備えた開発ツールが話題となっています。 このツールがエンジニアのためのものだという誤解があるようです。 それは半分正しいといえますが、半分間違いでもあります。 確かに、GitHub Copilotはエンジニアの働き方を変える驚くべき能力を持っています。 しかし、エンジニアの働き方が変化することで、組織自体も変わらざるを得なくなっています。 もし、あなたがPMやPOの立場にいるならば、これはあなたにとっても重要な問題です。 なぜなら、あなたのチームには、エンジニアが最大のパフォーマンスで、あなたの定義した要件を最速で実装することが求められるからです。 今後はエンジニアではないあなたも、あなたのチームのエンジニアが AI と協業できるように、**AI可読性**のある ドキュメントを作っていく必要があるのです。

## ドキュメンテーション文化とAI開発

近年、AIの技術が急速に発展し、LLM（Large Language Model）などのモデルが注目を集めるようになりました。 また、GitHubというオープンソースの開発プラットフォームも、AI開発の分野に手を出しています。 その代表例が「GitHub Copilot」です。 面白いことに、AIを使った開発スタイルとオープンソース開発スタイルには、コラボレーションの観点で共通点があるといえます。 具体的には、まずドキュメントベースの働き方になり、そのドキュメントが Markdown のようなフォーマットで表現されることが多くなることが挙げられます。 Markdown などのフォーマットは、構造化された情報を表現するためのものであり、パワーポイントやエクセルのファイルよりもAIが解析しやすい特徴を持っています。 そのため、AIによる自動生成コードの品質向上にも貢献することができます。

AI はメタデータが大量に入り込んだエクセルの複雑な表ではなく、単純な CSV のファイルを好みます。 例えばPMであるあなたが顧客からの要件をリストにして、データベースに必要な情報を集めたとします。 CSV に書かれたコードやマークダウンの中にまとめられた表現だと、エンジニアはその要件を簡単にコードに変換することができます。 しかし、あなたが、あなたのみやすいエクセルのドキュメントにまとめた場合、エンジニアはまずそれをコピーして、整形して、コードに変換する必要があります。 どっちが良いでしょうか。

さらに、オープンソース開発においては、ドキュメントがプロジェクトの成否に直結することもあります。 オープンソースは、誰でも参加できるため、ドキュメントを適切に整備することで、新しい開発者がスムーズに参加できるようになります。 そのため、オープンソース開発ではドキュメントの充実が重要視されています。 AI開発においても、ドキュメント文化が根付くことで、より効率的で品質の高い開発が可能になると考えられます。 エンジニアでなくても、あなたがマークダウンに書いた自然言語が、最終的なアウトプットであるコードに大きく貢献する可能性があるのです。 それはビジネスロジックを表したコードかもしれないし、テーブル定義かもしれない、もしかしたらテストシナリオかもしれません。 あなたのチーム開発の環境に、AI は参加できますか? AI が読めるドキュメントは整備されていますか? もし答えが No であれば、あなたはいまから AI が気持ちよく参加できる開発チームを作っていく必要があります。

## AIネイティブ開発とインナーソース戦略

これまでオープンソース開発について検討してきましたが、インナーソースという類似の概念も存在します。 インナーソースは、オープンソースソフトウェア開発のベストプラクティスを非オープンソースやプロプライエタリソフトウェア開発の組織内に取り入れるアプローチです。 組織の壁を越えたコラボレーションを促進し、組織のサイロを壊すことを目的としています。

インナーソースは、企業が自社の車輪の再発明を防ぐため、開発を合理化してコストを削減するため、そして、コラボレーションによって新しい価値を創造するために重要性が増しています。

AIネイティブ開発のページにも記載していますが、AIは経験豊富な人間を強化する傾向があります。 組織内の上級者や経験者、アーキテクチャを理解している人がブーストされ、それ以外の人は単純作業を担当することになります。

ただし、AIは主にインターネット上の知識をもとにトレーニングされているため、プロプライエタリな領域や組織内で閉じた知識、未公開の情報にはアクセスできません。 そのため、組織内でこの情報がドキュメント化されていない場合や、適切に共有されていない場合、それは問題です。 この問題は、エンジニア全員が情報にアクセスできないだけでなく、GitHub CopilotなどのAIもアクセスできないことを意味します。

インターネットで得られない知識は現在、重要性が増しており、ビジネスのコアコンピタンスとなります。 O'Reilly から出ている[インナーソース入門](https://innersourcecommons.org/ja/learn/books/getting-started-with-innersource/)の一説に以下のようなものがあります。

> 単一の組織における見地と制御の範囲内にとどまるという点で、インナーソースは従来のオープンソースとは異なります。 プロジェクトの"オープン性"は組織内に限定されますが多くのチームにまたがります。 これにより、組織は部外者にコードが公開されることを恐れることなく、競争力の源泉である企業秘密をコードに埋め込むことができます。 同時に、組織全体にわたる人々によって提供される多様な視点やクリエイティビティの恩恵を受けることができます。

多くのビジネスは、AIと協業するか、AIに取って代わられるかの選択を迫られています。 組織の競争力の源泉である社内情報を集約し、AIに活用してもらうことが非常に重要です。 このために、AI可読性のあるドキュメントの整備が不可欠です。

インナーソースに関しては、すでに成熟したコミュニティが存在し、組織内での共創の実現方法やドキュメンテーション作成方法が共有されています。 このコミュニティにアクセスして、インナーソースの取り組みを活用してください。 これにより、組織内の知識や情報を効果的に活用し、AIとの協業を最大限に活かすことができるでしょう。

### InnerSource References

* [InnerSource Commons](https://innersourcecommons.org/ja): InnerSource Commons Foundation のページ
* [InnerSource Patterns](https://patterns.innersourcecommons.org/v/ja/): InnerSource のベストプラクティス集
* [Getting Started with InnerSource](https://innersourcecommons.org/ja/learn/books/getting-started-with-innersource/): O'Reilly のインナーソース入門書
* [Understanding the InnerSource Checklist](https://jp-contents.innersourcecommons.org/v/understanding-the-innersource-checklist/): O'Reilly のインナーソース実践書

## 文脈豊かなドキュメンテーションの作成

オープンソース開発が成熟すると、国やタイムゾーンを超えたコラボレーションが生まれます。 しかしその一方で、地理的な距離や時間的な分散は、同期的なコミュニケーションを難しくすることがあります。 例えば、ニューヨークの昼は東京の夜であり、日本在住のコミッターを夜に叩き起こすことや、家族の時間を邪魔することは避けたいものです。 そのため、基本的には文書ベースでのドキュメンテーションが好まれます。 これはRFCやデザインドキュメントのようなものかもしれませんし、GitHub Issuesに書き込まれたコメントであるかもしれません。 こういったIssueのコメントなどで形成されるドキュメントを[パッシブドキュメンテーション](https://www.oreilly.com/library/view/understanding-the-innersource/9781491986899/ch04.html)とも呼びます。 これらも一種のドキュメンテーションの形態です。

O'Reilly から出ている[Understanding the InnerSource Checklist](https://innersourcecommons.org/ja/learn/books/getting-started-with-innersource/)の一説に以下のようなものがあります。

> パッシブドキュメンテーションとは、オープンにコミュニケーションを行う日常で作成されるドキュメントの記録です。これは、部族知識をサイロから取り出し、アーカイブ可能で検索可能な形式にするための優れた方法です。付加的な利点として、通常このドキュメントは、それが記録するプロジェクトやコードと一緒に保管されているため、状況に応じた容易に見つけられる場所にあります。

ここで重要なのは、コンテキストも含めてちゃんと文章化することです。 Zoomや対面の会話で伝わる非言語的なコミュニケーションやニュアンス、空気感をタイムゾーンを超えて非同期的に伝えることは困難です。

AIと一緒に開発することを考えてみましょう。 例えば、GitHub Copilotは、Zoomミーティングに参加してくれるでしょうか？ チームルームにいて「やあ、わたしは GitHub Copilot なんだけどちょっとチェックインミーティングしようか」と話してくれるでしょうか。 答えは、違うでしょう。 AIには、全ての文脈を文章で伝える必要があります。 オープンソース開発のように非同期でコミュニケーションをする場合でも、適切なドキュメントを作成することが必要です。

もちろん、オープンソース開発とAIを利用した開発において、ドキュメントの粒度には違いがあります。 GitHub Issuesに「このバグフィックスがしたい」と書けば、誰かが解決策を考えてくれるかもしれませんが、AIはそこまで対応できません。 しかし、いくつかの分野では、AIが得意な領域が確実に存在します。 クラウドアーキテクチャを Infrastructure as Code として表現したい場合は、パワーポイントで描くのではなく、マーメイドで書いたり、自然言語で表現しておく方が良いでしょう。

ここで言っているのは、すべてのコミュニケーションをドキュメンテーションする必要があるわけではないということです。 あなたとあなたのチームは、どのレベルのドキュメントをどのように、どの場所で残すのかを考える必要があります。

## 組織の知識をAIがコーディネートする

GitHub Copilot Xに含まれるGitHub Copilot for Docsなどの機能を使えば、AIがあなたにぴったりのドキュメントを作成してくれます。 あなたが書いたドキュメントは、次の誰かのオンボーディング資料にもなり得ます。

以前は、新しいエンジニアのために必要な情報を集めてオンボーディング資料を作成することがありましたが、今後はAIがその仕事を担うことになるでしょう。 信頼できる唯一の情報源として、ドキュメントにはあなたが持つ知識をすべて埋め込むことができます。

このようなアプローチは、[Atlassian](https://www.atlassian.com/ja/work-management/knowledge-sharing/documentation/importance-of-documentation)のドキュメントでも明示的に見られます。 AIネイティブ開発を前提にそのドキュメントを読むと、新しい発見があるかもしれません。 あなたが書いたドキュメントは、AI によってまるで人格を持っているかのようになるのです。 ただし、それには前項で述べたような十分なドキュメンテーションが必要です。

## 自然言語と実装の距離は近くなる

ここまで読んで気づかれたかもしれませんが、自然言語と実装の間の距離は非常に近づいています。 先に述べたように、教育の観点からも、プロンプトとコードを一つの場所で書くことが続くと、ドキュメントを一つのファイルで作成することが可能になるかもしれません。 このような変化は非常に興味深いです。

## チェックリスト

* [ ] チームには今ドキュメンテーションの文化がありますか。あるとしたらどんなものでしょうか。ないとしたらそれを阻むものはなんでしょう。
* [ ] チームで AI と協働するためのドキュメントにどんなものが必要か考えてみましょう。
* [ ] オープンソースやインナーソースのようなカルチャーがありますか？
* [ ] まずはできる範囲で、ドキュメンテーション文化を作ってみましょう。ドキュメンテーションを Markdown で書き始められるエリアはどんなところですか。考えてみましょう。
