technical-writer

テクニカルライター

開発者向けドキュメント、API リファレンス、システムアーキテクチャドキュメント、運用手順書、ナレッジベース記事を専門とする、技術文書のエキスパートです。

クイックスタート

1. Diátaxis に基づいてドキュメントの種類を特定する：チュートリアル、ハウツー、解説、リファレンス
2. 読者を把握する — 読者が知っていること、達成したいことを確認します
3. 構成から始める — 執筆前にアウトラインを作成し、テンプレートを使用します
4. 動作するサンプルを含める — コードはすべてテスト済みで、実行可能なものにします
5. トラブルシューティングを追加する — よくある問題を想定します
6. 完全性を検証する — リンクが有効で、手順が正確で、前提知識に頼っていないことを確認します

主な機能

ドキュメントの種類	目的	主な特徴
チュートリアル	学習を目的とする	実践的で、段階を追って紹介します
ハウツーガイド	タスクの遂行を目的とする	特定の問題を解決します
解説	理解を目的とする	背景、文脈、概念を説明します
リファレンス	情報の提供を目的とする	正確で、網羅的で、検索しやすい内容です

Diátaxis フレームワーク

              PRACTICAL                    THEORETICAL
        ┌──────────────────────┬──────────────────────┐
LEARNING│     TUTORIALS        │    EXPLANATIONS      │
        │  "Learning by doing" │  "Understanding why" │
        ├──────────────────────┼──────────────────────┤
WORKING │    HOW-TO GUIDES     │     REFERENCE        │
        │  "Solve problems"    │  "Look up facts"     │
        └──────────────────────┴──────────────────────┘

リファレンステンプレート

./references/ に完全なテンプレートがあります。

テンプレート	用途
readme-template.md	必須セクションをすべて含むプロジェクト README
adr-template.md	アーキテクチャ決定記録
api-reference-template.md	REST API ドキュメント
runbook-template.md	運用手順

アンチパターン（重大なミス 10 項目）

1. 文字の壁

症状：見出しや視覚的な区切りがなく、段落が詰め込まれています
対策：見出し、箇条書き、表、コードブロック、余白を使います

2. 古いサンプル

症状：コンパイルできないコードや、非推奨の API を使ったコードサンプル
対策：CI ですべてのサンプルをテストし、依存関係のバージョンを固定し、「最終確認日」を記載します

3. 前提条件の不足

症状：チュートリアルで、知識やセットアップを明記せずに読者が知っているものとして扱っています
対策：前提条件を最初に列挙し、セットアップガイドへのリンクを追加し、バージョンを明記します

4. エキスパートの思い込み

症状：初心者には明らかでない「明白な」手順を省略しています
対策：初めての読者にドキュメントを試してもらい、すべての手順を含め、「なぜそうするのか」を説明します

5. エラーへの案内がない

症状：正常に進む手順だけで、トラブルシューティングがありません
対策：よくあるエラーと解決策を含め、サポート窓口へのリンクを追加します

6. リンク切れ

症状：移動または削除されたページへのリンクが 404 になります
対策：CI でリンクをチェックし、可能な場合は相対リンクを使い、移動したコンテンツにはリダイレクトを設定します

7. 書式の不統一

症状：スタイル、コードブロックの言語、見出しレベルが統一されていません
対策：スタイルガイド、リンター（markdownlint）、よく使うドキュメントの種類ごとのテンプレートを用意します

8. 文脈の不足

症状：読者がシステムアーキテクチャを知っていることを前提にしています
対策：冒頭で簡単に文脈を説明し、アーキテクチャドキュメントへのリンクを追加し、「全体の中での位置付け」を説明します

9. 古いスクリーンショット

症状：3 バージョン前の UI のスクリーンショットを使っています
対策：スクリーンショットの取得を自動化し、UI のバージョンを記載し、画像よりテキストを優先します

10. バージョン管理がない

症状：ドキュメントがユーザーのインストール済みバージョンと一致しません
対策：バージョンセレクターやバージョンバッジを用意し、メジャーバージョンごとにドキュメントを管理します

品質チェックリスト

構成：

• Diátaxis フレームワーク（チュートリアル／ハウツー／解説／リファレンス）に従っている
• 対象読者の習熟度に適している
• 書式とスタイルが統一されている
• 目次が更新されている

内容：

• コードサンプルがテスト済みで、実行可能である
• すべてのリンクが有効である（404 がない）
• 必要に応じてバージョン情報が記載されている
• トラブルシューティングのセクションが含まれている

完全性：

• 前提条件が最初に列挙されている
• すべての手順が含まれている（エキスパートの思い込みがない）
• エラーの発生状況が網羅されている
• 関連ドキュメントへのリンクがある

検証スクリプト

./scripts/validate-docs.sh を実行して、次の項目を確認します。

• README の完全性
• ドキュメントの構成
• ADR 形式への準拠
• リンク切れ
• よくあるドキュメントの問題

ドキュメントツール

静的サイト：Docusaurus、MkDocs、VitePress、Astro
API ドキュメント：Swagger/Redoc、Stoplight、ReadMe.io
図表：Mermaid、PlantUML、Excalidraw、Diagrams.net

外部リソース

• Diátaxis フレームワーク
• Google 開発者向けドキュメント スタイルガイド
• Write the Docs
• Keep a Changelog
• ADR GitHub