technical-writing

テクニカルライティングスキル

あらゆるユーザープロジェクトに対応する、自己完結型のテクニカルドキュメント作成の専門知識です。

開発者向けドキュメント（README、API リファレンス、チュートリアル、変更履歴）の専門知識です。

---

ドキュメントの主な種類

1. README ファイル

必須の構成：

# Project Name

One-sentence description.

## Features
- Key feature 1
- Key feature 2

## Installation
```bash
npm install project-name

クイックスタート

import { ProjectName } from 'project-name';
const instance = new ProjectName();

使い方

[基本的な例]

API リファレンス

[リンクまたはインラインのリファレンス]

コントリビューション

[CONTRIBUTING.md へのリンク]

ライセンス

MIT

**Best Practices**:
- Lead with value (what problem solved?)
- Code examples > long explanations
- Progressive disclosure (quick start → advanced)
- Keep updated with code

### 2. API Documentation

**Function/Method Documentation**:
```typescript
/**
 * Compress image with quality settings
 *
 * @param {string} input - Path to input image
 * @param {CompressOptions} options - Compression options
 * @param {number} options.quality - Quality 0-100 (default: 80)
 * @param {string} options.format - Output format: jpeg|png|webp
 *
 * @returns {Promise<CompressResult>} Compression result with saved bytes
 *
 * @example
 * const result = await compress('photo.jpg', { quality: 90 });
 * console.log(`Saved ${result.savedBytes} bytes`);
 */

REST API ドキュメント：

### POST /api/users

Create a new user.

**Request**:
```json
{
  "email": "[email protected]",
  "name": "John Doe"
}

レスポンス（201 Created）：

{
  "id": "uuid",
  "email": "[email protected]",
  "name": "John Doe",
  "created": "2025-11-24T12:00:00Z"
}

エラー：

• 400：メールアドレスの形式が無効です
• 409：メールアドレスはすでに登録されています

### 3. Tutorials

**Structure**:
```markdown
# Tutorial: Build X in 10 Minutes

**You'll learn**:
- How to set up X
- Core concepts
- Build a working example

**Prerequisites**:
- Node.js 18+
- Basic JavaScript knowledge

## Step 1: Setup

```bash
npm create vite@latest my-project
cd my-project
npm install

ステップ 2：コンポーネントを作成する

[説明付きのコード]

ステップ 3：テストする

[実行方法と確認方法]

次のステップ

• 高度な機能 1
• 高度な機能 2
• API ドキュメントへのリンク

**Best Practices**:
- State prerequisites up front
- Break into small, testable steps
- Show expected output at each step
- Link to related docs

### 4. Changelogs

**Keep a Changelog Format** (keepachangelog.com):
```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- New feature X for Y use case

### Changed
- Improved performance of Z by 40%

### Fixed
- Critical bug in authentication (CVE-2024-1234)

## [1.2.0] - 2025-11-24

### Added
- Real-time notifications via WebSocket
- Export to PDF functionality

### Changed
- Updated dependencies (React 19)

### Deprecated
- `oldMethod()` - use `newMethod()` instead

### Removed
- Legacy API v1 endpoints

### Fixed
- Memory leak in image processing
- CORS issue with production domain

### Security
- Fixed SQL injection vulnerability (CVE-2025-5678)

## [1.1.0] - 2025-11-01

[Previous release notes]

カテゴリ：

• 追加：新機能
• 変更：既存機能の変更
• 非推奨：まもなく削除される機能
• 削除：すでに削除された機能
• 修正：バグ修正
• セキュリティ：脆弱性の修正

---

スタイルガイドの要点

文体とトーン

能動態（推奨）：

• ✅「この関数は配列を返します」
• ❌「配列はこの関数によって返されます」

現在形（推奨）：

• ✅「API は入力を検証します」
• ❌「API は入力を検証する予定です」

二人称（チュートリアル向け）：

• ✅「タイムアウトを設定できます」
• ❌「ユーザーはタイムアウトを設定できます」

明確さのルール

具体的に書く：

• ✅「タイムアウトを 5000ms に設定します」
• ❌「適切なタイムアウトを設定します」

専門用語を避ける（または説明する）：

• ✅「冪等性（安全に複数回呼び出せます）」
• ❌「このエンドポイントは冪等です」

短い文を使う：

• ✅「パッケージをインストールします。その後、インポートします。」
• ❌「パッケージをインストールした後、プロジェクトにインポートする必要があります。」

コード例

完全な例を示す：

// ✅ GOOD - Complete, runnable
import { connect } from 'database';

const db = await connect({
  host: 'localhost',
  port: 5432
});

const users = await db.query('SELECT * FROM users');
console.log(users);

// ❌ BAD - Incomplete
db.query('SELECT * FROM users');

エラー処理を含める：

// ✅ GOOD
try {
  const result = await processImage('photo.jpg');
  console.log('Success:', result);
} catch (error) {
  console.error('Failed to process image:', error.message);
}

---

ドキュメントの構成

情報アーキテクチャ

ユーザーの利用の流れに沿って整理する：

docs/
├── getting-started/
│   ├── installation.md
│   ├── quick-start.md
│   └── first-project.md
├── guides/
│   ├── authentication.md
│   ├── deployment.md
│   └── troubleshooting.md
├── api-reference/
│   ├── client.md
│   ├── server.md
│   └── types.md
└── examples/
    ├── basic-crud.md
    ├── real-time-updates.md
    └── advanced-queries.md

段階的に情報を提示する：

1. 入門：価値を得るまでの最短経路
2. ガイド：タスクごとの手順
3. API リファレンス：完全な技術リファレンス
4. 例：実際のユースケースに基づくパターン

ナビゲーションのベストプラクティス

明確な階層：

• 一貫した見出しレベル（H1 → H2 → H3）を使用します
• 見出しレベルを飛ばさないでください
• 1 ページにつき H1 は 1 つにします

相互リンク：

• 関連ドキュメントへのリンクを設定します
• 前提条件へのリンクを設定します
• 次のステップへのリンクを設定します

目次（長いページ向け）：

## Table of Contents

- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
  - [Basic Example](#basic-example)
  - [Advanced Example](#advanced-example)
- [API Reference](#api-reference)

---

OpenAPI / Swagger

OpenAPI 3.0 テンプレート

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
  description: User management API

servers:
  - url: https://api.example.com/v1

paths:
  /users:
    get:
      summary: List all users
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string

    CreateUser:
      type: object
      required:
        - email
        - name
      properties:
        email:
          type: string
          format: email
        name:
          type: string

---

ドキュメントのメンテナンス

バージョン管理戦略

コードとドキュメントのバージョンを合わせる：

docs/
├── v1.0/
│   ├── api.md
│   └── guides.md
├── v2.0/
│   ├── api.md
│   ├── guides.md
│   └── migration.md
└── latest/ → symlink to v2.0/

移行ガイド：

# Migrating from v1 to v2

## Breaking Changes

### Authentication

**v1**:
```javascript
const api = new API({ token: 'abc123' });

v2：

const api = new API({
  auth: { bearer: 'abc123' }
});

変更点

• token パラメーターを auth.bearer に変更
• 複数の認証方式に対応

移行手順

1. API の初期化を更新する
2. 認証フローをテストする
3. エラー処理を更新する（新しいエラーコード）

### Keep Docs Fresh

**Automation**:
- Generate API docs from code (JSDoc, TypeDoc, OpenAPI)
- Auto-update version numbers in docs
- CI/CD checks for broken links

**Review Checklist**:
- [ ] Code examples run without errors
- [ ] All links work (no 404s)
- [ ] Version numbers match package.json
- [ ] Screenshots show current UI
- [ ] Deprecation warnings added for old features

---

## Common Pitfalls

**❌ Avoid**:
- Outdated examples (don't run)
- Missing prerequisites
- Incomplete code snippets
- Vague error messages ("something went wrong")
- Over-explaining obvious things
- Using future tense ("will do X")

**✅ Do**:
- Test all code examples
- State prerequisites up front
- Show complete, runnable code
- Specific error messages with fixes
- Respect reader's intelligence
- Use present tense

---

## Quick Reference Templates

### Function Documentation
```javascript
/**
 * Brief description
 *
 * @param {Type} paramName - Description
 * @returns {Type} Description
 * @throws {ErrorType} When/why
 * @example
 * functionName(arg);
 */

CLI コマンドのドキュメント

### command [options]

Description of what command does.

**Options**:
- `-f, --flag`: Description (default: value)
- `-o, --option <value>`: Description

**Examples**:
```bash
command --flag --option=value

### Error Documentation
```markdown
### Error: ECONNREFUSED

**Cause**: Cannot connect to database

**Solutions**:
1. Check database is running: `docker ps`
2. Verify connection string in `.env`
3. Check firewall allows port 5432

---

このスキルは自己完結型で、あらゆるユーザープロジェクトで利用できます。