# Documentation Writing

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

- Skill: `tomevault-io/documentation-writing-3` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/documentation-writing-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/documentation-writing-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-writing-3

---


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

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

## When to Use

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

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

## 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文字前後を目安にし、長い文は分割する
- 文末は「。」で終える（「：」で終えない）
- 専門用語は初出で短く説明する。略語は正式名称を併記する
- 受動態より能動態を優先する（「〜されます」→「〜します」）
- 箇条書きで情報を整理し、段落は1トピックに絞る

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

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

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

以下は技術ドキュメントでも避ける。

| 避ける | 代替 |
|--------|------|
| 「重要:」「注意:」などの機械的プレフィックス | 見出しや通常文で述べる |
| 「革命的」「完璧な」などの誇張 | 事実・数値・条件で述べる |
| ダッシュ区切り（`——` / `—`）で文をつなぐ | 文を分ける、括弧、「つまり」 |
| 同じ言い回しの繰り返し | 具体例・手順・表で置き換える |
| 冗長な前置き（「本ドキュメントでは〜」の連発） | 目的が分かれば省略 |

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

### コード例の品質

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

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

#### 内容

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

#### 文章

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

#### 構成

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

### 出力の進め方

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

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