ドキュメントの書き方

目次

• 概要
• ドキュメントの種類
• 読者と目的を決める
• Diátaxisで整理する
• README
• 設計メモ
• ADR
• APIドキュメント
• 変更履歴
• 読みやすくする技術
• 手順を書く
• コード例を書く
• 図表を使う
• レビューされやすいドキュメント
• 古くなりにくくする
• ドキュメントを運用する
• 品質チェックリスト
• ドキュメント品質のメトリクス
• Diataxis（ダイアタクシス）フレームワーク
• Architecture Decision Records (ADR)
• OpenAPI/AsyncAPI による インターフェース仕様
• ドキュメント品質チェックリスト
• ドキュメント自動生成ツール
• ドキュメント体系の補足
• まとめ
• 参考文献

概要

ドキュメントは、コードだけでは伝わりにくい文脈、判断、使い方を残すためのものです。よいドキュメントは、読む人の次の行動を楽にします。

ドキュメントの種類

重要なのは、1つの文書にすべてを詰め込まないことです。初学者向けのチュートリアルに詳細仕様を混ぜると読みにくくなり、referenceに背景説明を混ぜすぎると探しにくくなります。

読者と目的を決める

ドキュメントを書く前に、読者と目的を1文で決めます。

この文書は、初めてこのリポジトリを触る開発者が、localでbuildできるようになるためのものです。

確認する問いです。

読者の状態によって、必要な書き方は変わります。

Diátaxisで整理する

Diátaxisは、ドキュメントを4種類に分けて考える方法です。

たとえば「Dockerfile」なら、文書の種類で内容が変わります。

同じテーマでも、読者の目的が違えば文書を分けます。これだけで、かなり読みやすくなります。

README

READMEはプロジェクトの玄関です。

含めるとよいものです。

• 何のプロジェクトか
• 誰のためのものか
• セットアップ
• よく使うコマンド
• ディレクトリ構成
• deploy方法
• troubleshooting

例です。

# Project

## Setup

```sh
npm install
npm run build
```

READMEは長くなりすぎたら、詳細ページへ分けます。

READMEのよくある構成です。

# Project name

短い説明。

## Quick start

## Requirements

## Common commands

## Directory structure

## Development workflow

## Deployment

## Troubleshooting

## License

READMEで避けたいことです。

Quick startでは、成功確認まで書きます。

## Quick start

```sh
npm ci
npm run build
```

`dist/index.html` が生成されれば成功です。

設計メモ

設計メモは、まだ固まり切っていない考えを残す場所です。

書くとよい観点です。

• 解きたい問題
• 制約
• 候補案
• 採用案
• 捨てた案
• リスク
• 未決事項

設計メモは、完璧な仕様書でなくて構いません。思考の途中を共有することに価値があります。

設計メモは「決定前」の文書です。ADRは「決定後」の文書です。この違いを分けると、議論の途中と決定の記録が混ざりにくくなります。

設計メモのテンプレート例です。

# 設計メモ: 検索機能のindex方針

## 背景

## 目的

## 制約

## 候補

## 比較

## 推奨案

## 未決事項

ADR

ADR(Architecture Decision Record)は、重要な意思決定を記録します。

# ADR: CloudFront Functionsでclean URLを処理する

## Status

Accepted

## Context

S3 private bucket + CloudFront OACで配信している。

## Decision

CloudFront Functionで `/path` を `/path/index.html` へrewriteする。

## Consequences

S3側にredirect objectを置かずに済む。

ADRは、「なぜそうしたか」を未来の自分に残す道具です。

ADRを書くタイミングです。

ADRは長くしすぎない方が続きます。1 decision 1 ADRにすると探しやすく、更新もしやすくなります。

APIドキュメント

APIドキュメントでは、requestとresponseを明確にします。

GET /api/items

{
  "items": [
    {"id": "1", "name": "book"}
  ]
}

含めるものです。

• endpoint
• method
• request header
• request body
• response body
• status code
• error response
• 認証
• rate limit

APIドキュメントは、利用者が「安全に呼べる」ことが重要です。成功例だけでなく、error responseと制限を書きます。

POST /api/items
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "book"
}

{
  "id": "item_123",
  "name": "book",
  "created_at": "2026-04-29T12:00:00Z"
}

error responseの例です。

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "name is required",
    "request_id": "req_123"
  }
}

OpenAPIのような機械可読な仕様を併用すると、document、mock、client生成、testに使えます。ただし、OpenAPIだけでは背景や使い方までは伝わりにくいため、guideやexampleも一緒に置くと親切です。

変更履歴

Changelogは、利用者が変更の影響を確認するために読みます。

## 1.2.0

- Added: clean URL support
- Changed: sidebar grouping
- Fixed: broken appendix links

変更履歴は、commit logとは役割が違います。利用者にとって意味のある単位にまとめます。

Keep a Changelogの考え方では、変更を種類ごとに分類します。

悪い例です。

- fix
- update docs
- misc

良い例です。

## 1.3.0

### Added

- 付録にDockerfile実践を追加しました。

### Fixed

- サイドバーのappendix linkが切れる問題を修正しました。

利用者が知りたいのは、commitの粒度ではなく「自分に影響するか」です。

読みやすくする技術

• 最初に結論を書く
• 対象読者を明確にする
• 見出しで構造を作る
• 手順は番号付きにする
• コマンドはそのまま実行できる形にする
• 失敗例と確認方法を書く
• 古くなりやすい情報に注意する

文体の基本です。

日本語では、主語を省略しすぎると手順が曖昧になります。「誰が」「何を」「どこで」実行するかを必要に応じて書きます。

ローカル環境で次を実行します。

```sh
npm run build
```

手順を書く

手順文書では、読者が上から順に実行できることが大切です。

よい手順の要素です。

手順の例です。

## Build

Repository rootで次を実行します。

```sh
npm run build
```

`dist/` が生成され、`Built ... pages` と表示されれば成功です。

手順で避けたい書き方です。

コード例を書く

コード例は「正しいだけ」では不十分です。読者がそのまま使えるか、危険な誤解をしないかを考えます。

コード例に添える情報です。

悪い例です。

doThing()

良い例です。

import { buildSite } from "./build.js";

await buildSite({
  inputDir: "md",
  outputDir: "dist",
});

コード例では、placeholderを明確にします。

aws s3 sync dist/ s3://<bucket-name> --delete

<bucket-name> は実際のS3 bucket名に置き換えます。

図表を使う

図表は、文章より構造を伝えやすいときに使います。

図を入れる前に、「文章で説明しにくい関係があるか」を考えます。飾りの図は保守コストだけ増えます。

図には、本文で読み方を添えます。図だけ置くと、どこを見ればよいか分からないことがあります。

レビューされやすいドキュメント

ドキュメントもコードと同じくレビュー対象です。ただし、レビュー観点は少し違います。

レビューしやすいPRにするには、変更理由を書きます。

## 変更理由

初回セットアップ時にNode.jsのversionで詰まりやすいため、
READMEに確認コマンドと想定versionを追加しました。

ドキュメントのレビューでは、「正しいか」だけでなく、「読者が次の行動を取れるか」を見ます。

レビュー依頼時に書くとよいことです。

レビューしてほしい点:

- 手順が初見でも通るか
- 前提が抜けていないか
- 用語が分かりにくくないか
- 古くなりやすい値を書きすぎていないか

ドキュメントPRは、差分が大きいと読まれにくくなります。構成変更、本文追加、リンク修正、表記統一を分けられるなら分けるとレビューしやすいです。

古くなりにくくする

ドキュメントは時間とともに古くなります。古くなりにくくするには、変わりやすい情報を本文に埋め込みすぎないことが大切です。

古くなりやすいものです。

• version番号
• 料金
• UIのスクリーンショット
• 外部サービスの画面手順
• 人名や担当者
• 一時的な制限

古くなりにくくする書き方です。

Node.jsは `.node-version` を参照してください。

料金は公式pricing pageを確認してください。

本文に固定値を書く必要がある場合は、その値が変わったときにどこを更新すればよいか分かるようにします。

古くなりにくい文書は、source of truthを明確にします。

「この文書が正」なのか「設定ファイルが正」なのかが曖昧だと、すぐにズレます。

ドキュメントを運用する

ドキュメントは書いた瞬間から古くなり始めます。運用を仕組みに入れると、少し長持ちします。

運用の工夫です。

ただし、更新日だけを自動更新すると「新しそうに見える古い文書」になります。last reviewed は、人が確認した意味で使う方がよいです。

品質チェックリスト

書き終わったら、次を確認します。

• Architecture Decision Records
• Markdown Guide: Basic Syntax
• OpenAPI Initiative: What is OpenAPI?

ドキュメント品質のメトリクス

読み易さスコア

Gunning Fog Index (グニング指数):

GFI = 0.4 * (W/S + 100 * C/W)

W = 単語数
S = 文の数  
C = 複合字音節を含む単語数

GFI 12 = 高卒レベル（推奨）
GFI 16 = 大卒レベル（難しい）
GFI 20+ = 大学院レベル（避けるべき）

実装例

import re
from textblob import TextBlob

def calculate_gunning_fog(text):
    """グニング指数を計算"""
    sentences = len(re.split(r'[.!?]', text))
    words = len(text.split())
    
    complex_words = 0
    for word in text.split():
        # シラブル数が3以上 (複合字音節)
        if syllable_count(word) >= 3:
            complex_words += 1
    
    gfi = 0.4 * (words/sentences + 100 * complex_words/words)
    return gfi

# テキスト品質チェック
doc_text = """
The implementation of microservices architecture...
"""
gfi = calculate_gunning_fog(doc_text)
if gfi > 14:
    print("警告: ドキュメントが難しすぎます")

Diataxis（ダイアタクシス）フレームワーク

Diataxis (diataxis.fr) は、ドキュメントを4つの独立した領域に分けるフレームワーク:

        実践的          理論的
  
段階的  Tutorial        Explanation
        (学習)         (理解)
        
参照的  How-to          Reference
        (解決)         (情報)

実装パターン

Tutorial: 初心者向け、目的は完了

## 5分で始める

1. パッケージをインストール
   \`\`\`bash
   pip install mylib
   \`\`\`

2. 簡単な例を実行
   \`\`\`python
   from mylib import simple_function
   result = simple_function(42)
   print(result)
   \`\`\`

3. 出力を確認

結果、あなたはmylibを実行できました。次に...

How-to: 経験者向け、目的は問題解決

## キャッシュを有効にする方法

キャッシュを有効にするには、設定ファイルで以下を設定:

\`\`\`yaml
cache:
  enabled: true
  ttl: 3600
  backend: redis
\`\`\`

詳細な設定: [キャッシュ設定リファレンス](#ref)

Explanation: 概念を深く理解

## なぜキャッシュが必要か

キャッシュは...

### キャッシュの種類
- ローカルキャッシュ
- 分散キャッシュ
- CDNキャッシュ

それぞれのトレードオフ...

Reference: 辞書的、完全性が目標

## Configuration Reference

| パラメータ | 型 | デフォルト | 説明 |
|---|---|---|---|
| cache.enabled | bool | false | キャッシュの有効・無効 |
| cache.ttl | int | 3600 | TTL（秒） |
| cache.backend | str | "memory" | バックエンド |

Architecture Decision Records (ADR)

ADR (adr.github.io) は、アーキテクチャ決定を記録する標準フォーマット:

ADR テンプレート

# ADR 001: マイクロサービスアーキテクチャの採用

**Status**: Accepted (受け入れ済み)
**Context**: 2026-05-03

## Context (文脈)

単体アプリケーションはスケール限界に達した。
- デプロイ頻度: 月1回
- 障害の波及: 全サービス停止
- チーム間の依存: 高い

## Decision (決定)

マイクロサービスアーキテクチャに移行する。

## Consequences (結果)

**利点:**
- デプロイ独立性向上
- スケーラビリティ向上
- チーム自律性向上

**課題:**
- サービス間通信の遅延・不安定性
- 分散トランザクションの複雑性
- 監視・デバッグの難しさ

## Alternatives (検討した代案)

1. Monolith + バッチ処理
2. Modular Monolith

(各代案を却下した理由...)

## References (参考資料)

- Newman, S. (2015). Building Microservices
- [AWS Microservices Whitepaper]

OpenAPI/AsyncAPI による インターフェース仕様

OpenAPI スキーマ例

openapi: 3.0.0
info:
  title: Order API
  version: 1.0.0

paths:
  /orders:
    post:
      summary: 注文作成
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: 注文作成成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: バリデーションエラー
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    CreateOrderRequest:
      type: object
      required: [customer_id, items]
      properties:
        customer_id:
          type: string
          format: uuid
        items:
          type: array
          minItems: 1
          items:
            type: object
            properties:
              product_id:
                type: string
              quantity:
                type: integer
                minimum: 1

    Order:
      type: object
      properties:
        order_id:
          type: string
          format: uuid
        status:
          type: string
          enum: [pending, confirmed, shipped]
        created_at:
          type: string
          format: date-time

    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string

Swagger UI による ドキュメント生成

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()

@app.post("/orders", tags=["Orders"])
def create_order(order: CreateOrderRequest):
    """
    注文を作成します。
    
    - **customer_id**: 顧客ID（必須）
    - **items**: 注文アイテム配列（最小1件）
    
    Returns:
        Order: 作成された注文情報
    """
    pass

# Swagger UI は自動生成される
# http://localhost:8000/docs にアクセス

ドキュメント品質チェックリスト

[ ] 対象読者が明確か？（初心者/経験者/開発者）
[ ] 目的が明確か？（チュートリアル/リファレンス/解説）
[ ] 図表が正確か？
[ ] コード例が実行可能か？
[ ] 外部リンクが有効か？
[ ] 用語が一貫しているか？
[ ] グニング指数が12-14か？
[ ] モバイルデバイスで読みやすいか？
[ ] 多言語対応の計画があるか？
[ ] バージョン管理されているか？
[ ] アクセシビリティ対応（色覚異常、スクリーンリーダー）
[ ] SEOメタデータが設定されているか？

ドキュメント自動生成ツール

ドキュメント体系の補足

Diátaxis - ドキュメンテーション体系

4つのドキュメント類型: Diátaxis(https://diataxis.fr/)は、ドキュメンテーション設計の統一的な理論枠組みを提供するプラットフォームです。プロジェクト作者・コントリビューター・ユーザーの多くが陥る「ドキュメンテーションの曖昧性と重複」を解決するため、以下の4つの明確に異なるドキュメント種別を定義しています：

• Tutorials (チュートリアル): 学習者が確実に成功する体験を提供する。目的 = 初心者の学習支援。特性: 線形、手順的、実践的。例: 「初めてのNode.jsアプリケーション」「Reactで最初のコンポーネントを作る」

• How-to Guides (ハウツーガイド): 特定の実務課題を解決する道筋を示す。目的 = 既知の問題への解決手段提供。特性: 目的志向、順序依存、実装詳細を含む。例: 「PostgresからMySQLへの移行ガイド」「Docker環境でのデバッグ方法」

• Reference (リファレンス): APIやコマンドの詳細仕様を記載。目的 = 必要な情報への高速アクセス。特性: 網羅的、構造化、アルファベット順等で整理。例: 「Array.prototype.map() - MDN」「curl コマンドオプション一覧」

• Explanation (解説): 概念や設計思想を背景から説明。目的 = 深い理解の構築。特性: 理論的、背景説明、複数視点の呈示。例: 「なぜGitはブランチモデルを採用しているのか」「マイクロサービスアーキテクチャの設計原則」

実践的な利用: この4分類は、「大量のドキュメントをどう整理するか」という実務課題の解決に直結します。例えば、GitHubのREADME、公式サイト、API仕様書などを作成する際に、各ドキュメントが4つのうちどれに相当するかを明確にすることで、「混乱したドキュメント」から「役割が明確なドキュメント」への転換が可能になります。

Markdown Guide - マークアップ標準化

CommonMark仕様: Markdown Guide(https://markdownguide.org/)は、Markdown形式の標準化を推進するプラットフォームです。Markdown本来の仕様(original Markdown by John Gruber)、拡張仕様(GitHub Flavored Markdown, MultiMarkdown, Pandoc等)、および各種実装の差異を明確に記載しており、以下の内容が集約されています：

• Basic Syntax: 見出し、段落、強調、リスト、リンク、画像、コード等の基本要素
• Extended Syntax: テーブル、脚注、タスクリスト、定義、ハイライト等の拡張機能
• Markdown vs HTML: マークアップの選び分け基準
• Tools and Resources: Markdownエディタ、プレビューア、変換ツール

実装別の互換性マトリックス: 同サイトには、異なるMarkdown処理エンジン(Python-Markdown, Ruby-Kramdown, Pandoc等)がどの拡張構文をサポートしているかを示す比較表が掲載されており、「このプロジェクトで使用するMarkdownフレーバーはどれか」を判断する際の参考資料となります。

Keep a Changelog - 変更履歴のベストプラクティス

バージョン管理と変更通知: Keep a Changelog(https://keepachangelog.com/)は、ソフトウェアの変更履歴ファイル(CHANGELOG.md)の作成・維持に関するガイドラインを提供しています。以下の実践的な推奨事項が含まれます：

• セマンティックバージョニング(SemVer): MAJOR.MINOR.PATCH形式(例: 2.5.3)の採用
• 変更分類: Added(新機能), Changed(変更), Deprecated(廃止予定), Removed(削除), Fixed(バグ修正), Security(セキュリティ)
• 時系列順序: 最新の変更を上部に配置
• ユーザー向けの言語: 技術者でない利用者にも理解できる説明
• リリース日の記載: ISO 8601形式(YYYY-MM-DD)での日付

プロジェクト間の信頼構築: 明確で継続的に更新されるCHANGELOGは、「プロジェクト作者がユーザーの関心事(バグ、セキュリティ、互換性)を把握している」というシグナルとなり、ユーザーのプロジェクト信頼度向上に寄与します。

Architecture Decision Records (ADR) - 設計決定の記録

決定記録のテンプレート: adr.github.io(https://adr.github.io/)が提供するアーキテクチャ決定レコード(ADR)形式は、技術的意思決定を「なぜそう決めたのか」という背景とともに記録する標準的なアプローチです。以下の構成要素が含まれます：

• Status: Proposed(提案), Accepted(採択), Deprecated(非推奨), Superseded(置き換え)
• Context: 決定が必要だった状況・背景
• Decision: 実際の決定内容
• Consequences: 決定の結果(利益、コスト、リスク)
• Alternatives Considered: 検討した代替案と却下理由

プロジェクト履歴の保全: ADRを段階的に記録していくことで、「今のアーキテクチャがどのような意思決定の積み重ねで形成されたか」を後発のコントリビューターが理解できるようになり、プロジェクトの保守性と継続性が向上します。例えば、「なぜマイクロサービスに移行したのか」「なぜこのDBを選んだのか」といった本質的な決定の根拠が保存されます。

OpenAPI Specification - REST API仕様の標準化

REST API の形式的定義: OpenAPI Specification(https://openapis.org/)は、REST APIの仕様を機械可読なYAML/JSON形式で記述するための標準です。以下の内容が定義されています：

• Endpoints: パス、HTTPメソッド(GET, POST等)、パラメータ
• Request/Response: ペイロードスキーマ、ヘッダー、ステータスコード
• Authentication: OAuth 2.0, API Key等の認証スキーム
• Documentation: エンドポイントの説明、使用例

ツール生態系: OpenAPI仕様を記述することで、以下のような自動生成ツーラが活用可能になります：

• Swagger UI: 対話的なAPI仕様ドキュメント
• Redoc: 読み易いAPIドキュメント
• OpenAPI Generator: クライアント・サーバーコードの自動生成
• Dredd: APIドキュメントとサーバーの一貫性検証

Write the Docs コミュニティ

ドキュメント作成者の実践知: Write the Docs(https://writethedocs.org/)は、ドキュメンテーション作成者向けのコミュニティプラットフォームであり、以下のリソースが提供されています：

• Documentation Guide: 言語別・用途別のドキュメント作成ガイド
• Books: 「The Good Documentation」「Becoming a Better Technical Writer」等の推奨図書
• Conferences and Events: ドキュメンテーション専門の国際カンファレンス
• Slack Community: 実務的な質問・知見共有のコミュニティ

業界横断的な知見: テック企業、オープンソースプロジェクト、医療機器メーカーなど、多様な業界からのドキュメント作成者が参加しており、「どの産業でも共通する課題と解決法」が集約されています。

Google Developers Style Guide - テクニカルライティング標準

Googleの社内標準の公開: Google Developers(https://developers.google.com/)が公開するStyle Guideは、Googleの技術文書作成に用いられる標準に基づいており、以下の項目を規定しています：

• 用語の統一: 「user」vs「end user」、「API」の大文字化等
• 文体: アクティブボイスの推奨、一人称の最小化
• コード例: サニタイズ、実行可能性、バージョン表記
• 図表: 説明文、キャプション、アクセシビリティ

Microsoft Learn Documentation - エンタープライズドキュメンテーション

スケールでのドキュメント管理: Microsoft Learn(https://learn.microsoft.com/)は、数千のAPI、フレームワーク、サービスを網羅するドキュメントシステムであり、以下の特徴を示しています：

• モジュール化: 学習モジュール、ハンズオンラボ、参考資料の分離
• バージョン管理: 複数バージョンの並行サポート
• 多言語対応: 翻訳戦略、言語ごとの更新タイミング
• メトリクス: ドキュメント品質、利用者満足度の測定

まとめ

ドキュメントは、読者が次に何をすればよいかを明確にするための道具です。README、Tutorial、How-to、Reference、Explanation、ADR、Changelogの役割を分けると、必要な情報を必要な形で残しやすくなります。よい文書は、読者、目的、前提、手順、成功確認、保守方法が見える文書です。

Technical Writing の言語学的側面

簡潔性と精密性の両立: テクニカルドキュメント作成の中核課題は、「単純な言葉を使いながら、精密な意味を伝える」ことにあります。以下の技法が有効です：

• アクティブボイス: 「エラーが発生した」(受動)→ 「ファイルが見つかりません」(能動的に状況を説明)
• 第三者表現: 「私たちは推奨します」→ 「推奨される」(より客観的)
• 専門用語の定義: 初出時に注脚やリンクで定義し、二度目以降は用語のみで参照

読者カテゴリーの分離: Diátaxis の4分類の背後には、「異なる読者群(初心者、実務者、学究)に対して、異なるテキスト構成が最適」という言語学的知見があります。

ドキュメント品質メトリクス

可読性スコア: Flesch Reading Ease、Gunning Fog Index等のアルゴリズムにより、テクノロジー文書の理解難度を定量化できます。目安として Flesch Reading Ease スコア 60～70 は「高校レベルの読み易さ」を示します。

メンテナンス性: ドキュメントの「鮮度」は、前回更新からの経過時間で劣化します。以下のメトリクスが有用です： -「このドキュメントの最終更新は何日前か」

• 「参照リンク切れの割合」
• 「コード例の実行検証実施日」

セマンティックHTMLとドキュメント構造

見出しレベルの階層性: HTML5の <h1>, <h2>, <h3> は単なる視覚スタイルではなく、ドキュメント構造を表現する semantic マーキングです。スクリーンリーダーユーザーは、見出しの階層をナビゲートしてドキュメント全体を把握するため、見出しレベルの一貫性が不可欠です。

構造化データ: Schema.org の語彙(BreadcrumbList, FAQPage等)により、ドキュメントを機械可読な形式で記述でき、検索エンジンが構造を正確に理解できるようになります。

バージョン管理と更新戦略

リリースノート設計: CHANGELOGに加えて、以下の要素がドキュメント更新を効果的に伝達します：

• Breaking Changes: 既存ユーザーのコードに影響する変更の詳細
• Migration Guide: 旧バージョンからの移行手順
• Deprecation Notices: 将来削除予定の機能の警告と代替案

バージョン別ドキュメント: 複数バージョンをサポートする場合、ドキュメントサイトは「このドキュメントは 3.5.x 用」を明示し、ユーザーが正しいバージョンを参照できるよう支援します。

国際化と翻訳戦略

原言語の設計: 翻訳を前提としたドキュメント設計では、以下の原則が重要です：

• 曖昧な短縮形・スラングを避ける
• 文化固有の表現・例示を避ける(例: 「米国の企業では~」は翻訳時に地域固有の例に置き換え可能にする)
• 画像内のテキストは避け、図分けにする

翻訳メモリ: TM(Translation Memory)ツール(memoQ, Trados等)により、同じ用語は常に同じ訳語を充てることで、ドキュメント全体の用語一貫性を保証します。

ドキュメントのアクセシビリティ

代替テキスト(alt text): 図表には、スクリーンリーダー用の代替テキストが必須です。有効な alt text は「図の内容」を説明するもので、例：

• 悪い: “image1.png”
• 良い: “API呼び出しシーケンス図。クライアントがサーバーに GET リクエストを送信し、サーバーが JSON レスポンスを返す”

論理読み順: HTML構造は視覚レイアウトと異なる場合があります。スクリーンリーダーは HTML 構造に従って読み進めるため、CSS で視覚順序を変更しても読み順は変わりません。

参考文献

公式・標準

• Microsoft Writing Style Guide

講義・記事

• Google Developer Documentation Style Guide

解説・補助

• ADR GitHub Organization
• Write the Docs
• Diátaxis
• Keep a Changelog