# Documentation Writing

> プロジェクトの技術ドキュメント（README、手順書、設計メモ、API 説明など）を執筆・推敲する際のガイドライン。読者・目的に合わせた構成、日本語の明確さ、AIっぽい表現の排除を重視する。

- Skill: `redamoon/documentation-writing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add redamoon/documentation-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/redamoon/documentation-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: MIT
- Author: redamoon (https://skillmd.com/u/redamoon)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/redamoon/documentation-writing

---


# 技術ドキュメント執筆スキル

プロジェクト内の Markdown ドキュメントを、読者が目的を達成できる形で書く・直すためのガイドです。ブログ記事向けのプラットフォーム記法（Zenn / はてな / note）ではなく、**リポジトリやプロダクトの説明・運用・開発向け文書**を対象とします。

## When to Use

- README、CONTRIBUTING、CHANGELOG などリポジトリ文書を書く・更新するとき
- セットアップ手順、運用手順、トラブルシューティングを Markdown でまとめるとき
- API・モジュール・アーキテクチャの説明ドキュメントを新規作成・推敲するとき
- ADR（Architecture Decision Record）や設計メモを整理するとき
- 既存ドキュメントの構成見直しや「読みにくいので直して」と依頼されたとき
- ドキュメントのレビュー・品質チェックを行うとき

ブログ記事の執筆・投稿向けには、同リポジトリの `zenn-blog-writing` や `blog-workflow` を使う。

文章そのものの推敲（論証の厳密さ、冗長の排除、LLM っぽい表現の排除）は、文書の種類を問わず `japanese-prose-revision` に従う。

緩急やリズムの設計（`cognitive-rhythm-writing`）は、読み物性のある解説文に限って適用する。ADR の Context、設計メモの背景説明、アーキテクチャの解説などが該当する。README、手順書、リファレンスでは、目的や完了条件を先に明示することと、内容を予告する見出しが読者の要件なので、下記「文書タイプ別の推奨構成」を優先する。`cognitive-rhythm-writing` の議題表や進行予告の禁止と、`japanese-prose-revision` の「LLM っぽい表現の禁止」にある「予告と総括」は、これらの文書には当てない。

## Instructions

### 執筆の前提

1. **読者を決める**：新規参加者、日常開発者、運用担当、利用者のうち誰向けかで、深さと用語を変える
2. **目的を1文で決める**：読後に読者が何ができるようになるか（例: ローカルで起動できる、障害時にログを確認できる）
3. **既存ドキュメントを確認する**：重複セクションを増やさず、リンクでつなぐ
4. **事実と推測を分ける**：未確認の挙動は「想定」「要確認」と明記する

### 文書タイプ別の推奨構成

#### README（リポジトリの顔）

1. 何のプロジェクトか（1〜2文）
2. 主な機能・用途
3. 必要条件（ランタイム、ツール）
4. クイックスタート（最短で動かす手順）
5. 詳細ドキュメントへのリンク
6. ライセンス

#### 手順書（How-to）

1. 目的と完了条件
2. 前提（権限、環境、依存）
3. 手順（番号付き、1ステップ1アクション）
4. 確認方法（期待する出力・画面）
5. よくある失敗と対処

#### リファレンス（API・設定・コマンド）

- 項目ごとに同じテンプレート（名前、説明、型・引数、例、注意）
- 表または見出しでスキャンしやすくする
- 例はコピーしてそのまま使える形にする

#### ADR / 設計メモ

- **Context**：背景・課題
- **Decision**：採用した方針
- **Consequences**：メリット・デメリット・トレードオフ
- **Status**：提案中、承認済み、廃止のいずれかと、その日付

### 文体と日本語

- 本文は **ですます調** を基本とする
- 1文は60文字前後を執筆時の目安にし、長い文は分割する。textlint を使うプロジェクトでは、機械的な上限チェックは `sentence-length`（最大100文字）が担当する
- ただし `cognitive-rhythm-writing` の「短文化バイアスの禁止」のとおり、必要な文脈共有（範囲、観点、比較軸、未確定事項）を削って短くするのは緩急ではなく欠落である。削らずに分割できないときは60文字を超えてよい
- 文末は「。」で終える（「：」で終えない）
- 専門用語は初出で短く説明する。略語は正式名称を併記する
- 受動態より能動態を優先する（「〜されます」→「〜します」）
- 箇条書きで情報を整理し、段落は1トピックに絞る

### マークダウンの書き方

- 見出しは論理的な階層（`#` は文書タイトル1つのみ、本文は `##` から）
- 見出し内の太字は避ける
- ファイル名・コマンド・API パス・環境変数は **インラインコード**（バッククォート）で書く。太字と併用しない
- コードブロックには言語を指定する（`bash`, `typescript`, `json` など）
- リンクテキストは具体的にする（「こちら」だけにしない）
- スクリーンショットを使う場合は、何が写っているかキャプションで補足する

### AIっぽい文章の排除

技術ドキュメント固有の項目として、「重要:」「注意:」のような機械的プレフィックスを避ける。代わりに見出しを立てるか、通常の文で述べる。

これ以外の LLM っぽい表現と冗長は、`japanese-prose-revision` の「LLM っぽい表現の禁止」と「冗長の排除」に従う。ただし前置き（「本ドキュメントでは〜」）を省くのは、目的が本文から一意に読み取れるときだけとする。手順書やリファレンスの目的と完了条件は、前置きではなく読者の要件なので残す。

品質チェックに textlint を使うプロジェクトでは、編集後に **`textlint-blog` スキル**（またはプロジェクトの textlint 設定）で Markdown を検証する。

### コード例の品質

- 動作確認済み、または「要確認」と明記する
- バージョン・OS・ツールの前提を書く
- プレースホルダは `<YOUR_VALUE>` のように統一する
- シークレットや個人情報を例に含めない

### レビュー時のチェックリスト

#### 内容

- [ ] 読者と目的に合っているか
- [ ] 手順どおりに再現できるか（コマンド・パス・権限）
- [ ] 古い情報（廃止 API、削除済み機能）が残っていないか
- [ ] 他ドキュメントと矛盾していないか

#### 文章

- [ ] ですます調で統一されているか
- [ ] AIっぽい定型句やダッシュ区切りがないか
- [ ] 専門用語に初出説明があるか
- [ ] textlint を使う場合、エラーが解消されているか

#### 構成

- [ ] 見出し階層が飛び級になっていないか
- [ ] 目次やリンクで長文を辿りやすいか
- [ ] 重複セクションを統合できるか

### 出力の進め方

1. 不足情報があれば、読者・環境・完了条件を短く確認する
2. 既存ファイルを読み、追記か新規かを判断する
3. 構成案（見出し一覧）を示してから本文を書く（大きな変更のとき）
4. 変更点を箇条書きで要約する（何を追加・削除・移動したか）