# ドキュメントへの貢献

Goaのドキュメントを、正確で読みやすく、人にもコーディングエージェントにも役立つものに保つための指針。

Source: https://goa.design/ja/docs/contributing/

Relative links resolve against the source URL above.


ドキュメントのソースは[goa.designリポジトリ](https://github.com/goadesign/goa.design)にあります。誤りの報告や改善のプルリクエストを歓迎します。

## 情報の置き場所

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

- 型、サービス、メソッド、検証は[Goa DSLリファレンス](../1-goa/dsl-reference/)。
- HTTPの実装は[HTTPガイド](../1-goa/http-guide/)、gRPCは[gRPCガイド](../1-goa/grpc-guide/)。
- エージェントの設計は[Goa-AI DSLリファレンス](../2-goa-ai/dsl-reference/)、実行の契約は[ランタイム](../2-goa-ai/runtime/)。
- 可観測性は[Clue](../3-ecosystem/clue/)、分散イベントは[Pulse](../3-ecosystem/pulse/)、設計図は[Model](../3-ecosystem/model/)。

## 書き方

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

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

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

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

## 変更を確認する

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

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