documentation-templates

ドキュメントテンプレート

一般的なドキュメントの種類に対応するテンプレートと構成ガイドラインです。

---

1. README の構成

必須セクション（優先順）

セクション	目的
タイトル＋概要の一文	これは何ですか？
クイックスタート	5 分以内に実行する
機能	何ができますか？
設定	カスタマイズ方法
API リファレンス	詳細ドキュメントへのリンク
コントリビュート	貢献する方法
ライセンス	法的事項

README テンプレート

# Project Name

Brief one-line description.

## Quick Start

[Minimum steps to run]

## Features

- Feature 1
- Feature 2

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| PORT | Server port | 3000 |

## Documentation

- [API Reference](./docs/api.md)
- [Architecture](./docs/architecture.md)

## License

MIT

---

2. API ドキュメントの構成

エンドポイントごとのテンプレート

## GET /users/:id

Get a user by ID.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | Yes | User ID |

**Response:**
- 200: User object
- 404: User not found

**Example:**
[Request and response example]

---

3. コードコメントのガイドライン

JSDoc/TSDoc テンプレート

/**
 * Brief description of what the function does.
 * 
 * @param paramName - Description of parameter
 * @returns Description of return value
 * @throws ErrorType - When this error occurs
 * 
 * @example
 * const result = functionName(input);
 */

コメントを記述する場合

✅ コメントを記述する	❌ コメントを記述しない
理由（ビジネスロジック）	内容（明白な場合）
複雑なアルゴリズム	すべての行
明白でない動作	説明不要なコード
API コントラクト	実装の詳細

---

4. 変更履歴テンプレート（Keep a Changelog）

# Changelog

## [Unreleased]
### Added
- New feature

## [1.0.0] - 2025-01-01
### Added
- Initial release
### Changed
- Updated dependency
### Fixed
- Bug fix

---

5. アーキテクチャ決定記録（ADR）

# ADR-001: [Title]

## Status
Accepted / Deprecated / Superseded

## Context
Why are we making this decision?

## Decision
What did we decide?

## Consequences
What are the trade-offs?

---

6. AI フレンドリーなドキュメント

llms.txt テンプレート

AI クローラーとエージェント向け：

# Project Name
> One-line objective.

## Core Files
- [src/index.ts]: Main entry
- [src/api/]: API routes
- [docs/]: Documentation

## Key Concepts
- Concept 1: Brief explanation
- Concept 2: Brief explanation

MCP 対応ドキュメント

RAG インデックス作成向け：

• 明確な H1-H3 階層
• データ構造の JSON/YAML 例
• フローを示す Mermaid 図
• 単独で完結するセクション

---

7. 構成の原則

原則	理由
ざっと読めること	見出し、リスト、表
例を先に示す	説明だけでなく、実例を示す
段階的な詳細化	シンプル → 複雑
最新の状態に保つ	古い情報は誤解を招きます

---

覚えておきましょう： テンプレートは出発点です。プロジェクトのニーズに合わせて調整してください。