redamoon 技術ドキュメント執筆スキル
プロジェクト内の 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文で決める：読後に読者が何ができるようになるか（例: ローカルで起動できる、障害時にログを確認できる）
- 既存ドキュメントを確認する：重複セクションを増やさず、リンクでつなぐ
- 事実と推測を分ける：未確認の挙動は「想定」「要確認」と明記する
文書タイプ別の推奨構成
README（リポジトリの顔）
- 何のプロジェクトか（1〜2文）
- 主な機能・用途
- 必要条件（ランタイム、ツール）
- クイックスタート（最短で動かす手順）
- 詳細ドキュメントへのリンク
- ライセンス
手順書（How-to）
- 目的と完了条件
- 前提（権限、環境、依存）
- 手順（番号付き、1ステップ1アクション）
- 確認方法（期待する出力・画面）
- よくある失敗と対処
リファレンス（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 を使う場合、エラーが解消されているか
構成
- 見出し階層が飛び級になっていないか
- 目次やリンクで長文を辿りやすいか
- 重複セクションを統合できるか
出力の進め方
- 不足情報があれば、読者・環境・完了条件を短く確認する
- 既存ファイルを読み、追記か新規かを判断する
- 構成案（見出し一覧）を示してから本文を書く（大きな変更のとき）
- 変更点を箇条書きで要約する（何を追加・削除・移動したか）