# Documentation

> ドキュメントを日英二言語で整備するときに使う。新規ドキュメント追加・既存編集・命名規約・相互リンク・翻訳ミラーの同期方針の判断時にトリガーする。 Use when this capability is needed.

- Skill: `tomevault-io/documentation-3` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/documentation-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/documentation-3/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/documentation-3

---


# documentation

公開ツールやエージェント向けの READMEs / docs を、**英語を既定・日本語をミラー** として 2 言語で整備するための共通方針。

## 命名規約

- **英語版**: 拡張子なし — `README.md` / `docs/path.md` / `docs/content.md`
- **日本語版**: `.ja.md` 接尾辞 — `README.ja.md` / `docs/path.ja.md` / `docs/content.ja.md`
- 同一トピックの 2 言語版は **兄弟ファイル** として並べる（`docs/en/` のようなサブディレクトリで分けない）

## 言語セレクタヘッダー

各ファイルの H1 直下に、現在言語を太字・他言語をリンクで表すセレクタを置く。

英語版:

```markdown
# <Title>

> [日本語](./<basename>.ja.md) | **English**
```

日本語版:

```markdown
# <タイトル>

> **日本語** | [English](./<basename>.md)
```

トップレベル `README.md` / `README.ja.md` も同形式。

## 内部リンク

兄弟参照は **同言語の対応版** を指す。

- 英語版 (`docs/foo.md`) の `[bar](bar.md)` → 英語版 `bar.md`
- 日本語版 (`docs/foo.ja.md`) の `[bar](bar.ja.md)` → 日本語版 `bar.ja.md`

トップレベル README からの参照も同じ規則:

- `README.md` → `docs/foo.md`
- `README.ja.md` → `docs/foo.ja.md`

## 同期ルール

ドキュメントを編集するときは **両言語を同じ PR で更新** する。

- 新規追加: `foo.md` と `foo.ja.md` を同時に作成
- 内容変更: 片方だけの編集は許容しない（部分翻訳の取り残し原因）
- リネーム: 両言語版を同時にリネーム
- 削除: 両言語版を同時に削除

英語が源泉とは限らない。実装者が日本語で書いた内容を後から英訳しても、最終 PR では両方そろえる。

## 翻訳の取り扱い

- コードブロック・YAML・CLI 出力例・ファイルパス・パッケージ名は **逐語維持**
- 表のセル内テキストは翻訳、表構造は維持
- ツール固有名詞（Claude Code / Cursor / GitHub Actions / npm 等）は原語のまま
- 出力例の中の人間向けメッセージはその言語に合わせて訳す
- ソース整合性マーカー（プロジェクトが採用していれば）の行は逐語維持。ハッシュ・パスは言語ごとに変えない

## 新規ドキュメント追加時の手順

1. 英語版 `docs/<name>.md` を H1 + 言語セレクタヘッダー付きで作成
2. 日本語版 `docs/<name>.ja.md` を作成（同じ構造、翻訳した本文）
3. ソース整合性マーカーが必要なセクションは両言語版に同一で配置
4. `docs/README.md` と `docs/README.ja.md` の索引に追加
5. ルートの `README.md` / `README.ja.md` でも紹介すべきトピックなら追記
6. プロジェクトの doc lint がある場合はローカルで実行して検証
7. PR では両言語版を 1 コミットにまとめる

## 他スキルとの関係

- **implementation** — ドキュメント変更を含む実装でステップ 5 で命名・同期ルールを併用
- **improvement** — スキル紹介を更新する際の参照元
- **direction** — エージェント可読性（legibility）の観点で構造判断を伴うときに併用

## アンチパターン

- 片言語のみ更新して他方を放置 → 部分翻訳の取り残し原因
- 言語別にディレクトリを分ける（`docs/en/` / `docs/ja/` 等）→ 兄弟ファイル方式の方が検索性とリンク管理が単純
- セレクタヘッダーを省略 → 利用者が代替言語版に到達できない
- ソース整合性マーカーのハッシュを言語版ごとに変える → ソース 1 個に対し複数ハッシュは意味矛盾
- 翻訳ミラーを巨大 PR 検出（diff size 等）にカウントする → 構造的に大きくなる翻訳 PR で警告が誤発動する

---
> Source: [Mulyu/okite](https://github.com/Mulyu/okite) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-16 -->