ドキュメントへの貢献

ドキュメントのソースはgoa.designリポジトリにあります。誤りの報告や改善のプルリクエストを歓迎します。

情報の置き場所

各トピックの詳しい説明はひとつのページで管理し、他のページでは短く説明してリンクしてください。

• 型、サービス、メソッド、検証はGoa DSLリファレンス。
• HTTPの実装はHTTPガイド、gRPCはgRPCガイド。
• エージェントの設計はGoa-AI DSLリファレンス、実行の契約はランタイム。
• 可観測性はClue、分散イベントはPulse、設計図はModel。

書き方

最初に読者が実現できることを説明し、必要な前提条件と次の操作を示します。コード例はインポート、バージョン、設定を明示し、実行できる例と抜粋を区別してください。機能の説明はソースコードと照合し、計測していないトークン削減率や生産性を主張しません。

クイックスタートは最初の成功に集中させます。ガイドは具体的な作業を説明し、リファレンスは正確な契約を示します。既存のURLとアンカーは維持し、移動が必要なら転送を用意します。

コーディングエージェントにも読みやすくする

各節は必要な文脈を含め、専門用語を説明します。モデルが編集する設計・アプリケーションコードと、再生成するgen/を区別してください。開発手順が共通の説明です。構造の検証、認可、ビジネスルールの担当範囲を曖昧にしないでください。

変更を確認する

英語のソースはcontent/en/docs/です。翻訳は同じ構造のcontent/{lang}/docs/に置き、日本語は手動で更新します。画面の文字列はi18n/で管理します。コード、リンク、Hugoショートコードは翻訳しません。

make serveで表示を確認し、npm testと本番用ビルドを実行します。ナビゲーションやレイアウトを変更した場合は、モバイルとデスクトップ、両テーマ、翻訳ページを確認してください。詳細はリポジトリのREADMEと英語の貢献ガイドを参照してください。