今こそエンジニアはCode-basedなドキュメンテーションを行うべきだと思ったので、その思想と方法をまとめる
タイトルの内容について考え、社内向けに以下のDocumentation Guidelinesを作成しました。
プロダクト開発の効率を高めてくれて非常に有益なので共有します。
英語の原文の後に、AIによる機械的な翻訳を書いています。
Overview
Modern documentation requires both accuracy and efficiency. By leveraging AI-powered editors and code-based documentation, we can achieve both while maintaining high quality and consistency.
【日本語訳】
現代のドキュメンテーションには、正確性と効率性の両方が求められます。AI搭載のエディターやコードを活用したドキュメンテーションにより、高品質かつ一貫性のある情報を効率的に作成することが可能となります.
Our Philosophy
We believe in a new approach to documentation that puts AI capabilities at the center. In the era of AI agents that can read and understand codebases, documentation should be created through AI-human collaboration. To maximize AI's potential, we keep all code and documentation in a monorepo, enabling AI to access and analyze the entire codebase efficiently.
【日本語訳】
我々は、AIの能力を中心に据えた新しいドキュメンテーション手法を信じています。コードベースを読み解くことができるAIエージェントが登場した現代において、ドキュメンテーションは人間とAIの協働によって作成されるべきです。AIの可能性を最大限に引き出すため、すべてのコードとドキュメントをモノレポに集約し、AIがコード全体に効率的にアクセス・解析できるようにしています.
Evolution of Documentation Approaches
Traditional Tools and Their Limitations
Code-Based Tools (e.g., Docusaurus)
- ✅ Documentation stays in sync with code
- ✅ Version control integration
- ✅ Single source of truth
- ❌ Writing experience less intuitive
- ❌ Time-consuming content creation
- ❌ Manual updates required
【日本語訳】
- ✅ ドキュメントはコードと常に同期しています
- ✅ バージョン管理との統合がされています
- ✅ 一元管理された情報源
- ❌ 執筆体験が直感的ではありません
- ❌ コンテンツ作成に時間がかかります
- ❌ 手動での更新が必要です
Modern UI Tools (e.g., Notion)
- ✅ Intuitive UI/UX for writing
- ✅ Easy collaboration
- ✅ Rich text editing
- ❌ Disconnected from codebase
- ❌ Risk of outdated documentation
- ❌ Limited automation possibilities
【日本語訳】
- ✅ 執筆に直感的なUI/UX
- ✅ 簡単な共同作業が可能
- ✅ リッチテキスト編集ができます
- ❌ コードベースと連携していません
- ❌ ドキュメントが古くなるリスクがあります
- ❌ 自動化の可能性が限られています
The AI-Powered Solution
AI-powered editors transform documentation by combining and enhancing the benefits of both approaches:
【日本語訳】
AI搭載のエディターは、両アプローチの利点を組み合わせ、さらに向上させることでドキュメンテーションを変革します:
Code-Documentation Synergy
- AI seamlessly accesses and understands both code and documentation
- Enables automated documentation generation and updates
- Maintains a single source of truth in the monorepo
【日本語訳】
- AIはコードとドキュメントの両方にシームレスにアクセスし、理解します
- 自動的なドキュメント生成と更新を可能にします
- モノレポ内の一元管理された情報源を維持します
Enhanced Writing Experience
- Produces well-structured, consistent content
- Supports rich visualization through tools like Mermaid
- Provides standard development workflows (version control, reviews)
【日本語訳】
- 整然とした一貫性のあるコンテンツを生成します
- Mermaidなどのツールを利用して豊かなビジュアル表現をサポートします
- 標準的な開発ワークフロー（バージョン管理、レビュー）を提供します
Efficiency and Accuracy
- Generates accurate documentation rapidly
- Enables multilingual team collaboration
- Facilitates easy updates and maintenance
【日本語訳】
- 正確なドキュメントを迅速に生成します
- 多言語チームでの共同作業を可能にします
- 簡単な更新と保守を促進します
AI-Driven Documentation Workflow
This workflow illustrates how we create and maintain documentation:
- Engineers request documentation through AI-powered editors
- AI analyzes the codebase for context
- AI generates initial documentation
- Engineers review and provide feedback
- AI refines based on feedback
- Process repeats until quality is satisfactory
- Final documentation is committed
【日本語訳】
このワークフローは、ドキュメンテーションの作成および維持方法を示しています:
- エンジニアがAI搭載のエディターを通じてドキュメント作成をリクエストします
- AIがコードベースを解析し、文脈を把握します
- AIが初期のドキュメントを生成します
- エンジニアがレビューし、フィードバックを提供します
- AIがフィードバックに基づいて内容を改善します
- 品質が満足するまで、このプロセスを繰り返します
- 最終的なドキュメントがコミットされます
Implementation Guide
Required Tools
AI-Powered Editors
- Cursor (with Claude-3.5-Sonnet)
- VSCode with Cline
- Windsurf
【日本語訳】
- Cursor（Claude-3.5-Sonnet搭載）
- VSCode（Cline付き）
- Windsurf
Documentation Process
1. Preparation
- Ensure your editor has access to the codebase
- Identify the target audience and documentation type
【日本語訳】
- エディターがコードベースにアクセスできることを確認してください
- 対象読者とドキュメントの種類を特定してください
2. Creation
- Describe your documentation needs to the AI
- Point to relevant code directories or files
- Let AI analyze and generate content
【日本語訳】
- AIにドキュメントの要件を伝えてください
- 関連するコードディレクトリやファイルを指定してください
- AIに解析とコンテンツ生成を行わせてください
3. Review and Refinement
- Review AI-generated content thoroughly
- Provide specific feedback to AI
- Iterate until satisfied
- Commit when complete
【日本語訳】
- AIが生成した内容を十分にレビューしてください
- AIに具体的なフィードバックを提供してください
- 満足するまで繰り返してください
- 完了したらコミットしてください
Best Practices
1. Language
- Write all documentation in English
- Use AI for multilingual queries when needed
【日本語訳】
- すべてのドキュメントは英語で記述してください
- 必要に応じて、AIを利用して多言語対応の問い合わせを行ってください
2. Content Structure
- Use clear, hierarchical organization
- Create logical groupings of related content
- Utilize visual aids (diagrams, code examples)
- Maintain consistent formatting
- Include clear navigation and cross-references
【日本語訳】
- 明確で階層的な構成を使用してください
- 関連する内容を論理的にグループ化してください
- 図表やコード例などの視覚的補助を活用してください
- 一貫したフォーマットを維持してください
- 明確なナビゲーションとクロスリファレンスを含めてください
3. Quality Control
- Review technical accuracy
- Ensure completeness
- Verify code examples work
- Check for clear explanations
【日本語訳】
- 技術的な正確性を確認してください
- 内容が網羅されているか確認してください
- コード例が正しく動作するか検証してください
- 分かりやすい説明がされているか確認してください
4. Maintenance
- Update documentation when code changes
- Regular reviews for accuracy
- Remove outdated content
【日本語訳】
- コードが変更された場合、ドキュメントを更新してください
- 正確性を定期的にレビューしてください
- 古い内容は削除してください
Getting Started
- Set up an AI-powered editor
- Clone the repository
- Follow the workflow diagram
- Submit documentation changes via pull requests
【日本語訳】
- AI搭載のエディターをセットアップしてください
- リポジトリをクローンしてください
- ワークフローダイアグラムに従ってください
- プルリクエストを通じてドキュメントの変更を提出してください
Remember: The AI is a powerful tool, but you are responsible for the final quality of the documentation. Always review thoroughly and ensure accuracy.
【日本語訳】
注意: AIは強力なツールですが、最終的なドキュメントの品質に関してはご自身の責任となります。必ず十分にレビューし、正確性を確保してください.
Discussion