tomevault-io 技術ドキュメント執筆スキル
プロジェクト内の Markdown ドキュメントを、読者が目的を達成できる形で書く・直すためのガイドです。ブログ記事向けのプラットフォーム記法（Zenn / はてな / note）ではなく、リポジトリやプロダクトの説明・運用・開発向け文書を対象とします。
When to Use
- README、CONTRIBUTING、CHANGELOG などリポジトリ文書を書く・更新するとき
- セットアップ手順、運用手順、トラブルシューティングを Markdown でまとめるとき
- API・モジュール・アーキテクチャの説明ドキュメントを新規作成・推敲するとき
- ADR（Architecture Decision Record）や設計メモを整理するとき
- 既存ドキュメントの構成見直しや「読みにくいので直して」と依頼されたとき
- ドキュメントのレビュー・品質チェックを行うとき
ブログ記事の執筆・投稿向けには、同リポジトリの zenn-blog-writing や blog-workflow を使う。
Instructions
執筆の前提
- 読者を決める: 新規参加者 / 日常開発者 / 運用担当 / 利用者 — 誰向けかで深さと用語を変える
- 目的を1文で決める: 読後に読者が何ができるようになるか（例: ローカルで起動できる、障害時にログを確認できる）
- 既存ドキュメントを確認する: 重複セクションを増やさず、リンクでつなぐ
- 事実と推測を分ける: 未確認の挙動は「想定」「要確認」と明記する
文書タイプ別の推奨構成
README（リポジトリの顔）
- 何のプロジェクトか（1〜2文）
- 主な機能・用途
- 必要条件（ランタイム、ツール）
- クイックスタート（最短で動かす手順）
- 詳細ドキュメントへのリンク
- ライセンス
手順書（How-to）
- 目的と完了条件
- 前提（権限、環境、依存）
- 手順（番号付き、1ステップ1アクション）
- 確認方法（期待する出力・画面）
- よくある失敗と対処
リファレンス（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 を使う場合、エラーが解消されているか
構成
- 見出し階層が飛び級になっていないか
- 目次やリンクで長文を辿りやすいか
- 重複セクションを統合できるか
出力の進め方
- 不足情報があれば、読者・環境・完了条件を短く確認する
- 既存ファイルを読み、追記か新規かを判断する
- 構成案（見出し一覧）を示してから本文を書く（大きな変更のとき）
- 変更点を箇条書きで要約する（何を追加・削除・移動したか）
Source: redamoon/skills — distributed by TomeVault.