docs-as-marketing

マーケティングとしてのドキュメント

ドキュメントは、多くの場合、開発者が製品と意味のある形で初めて触れる場です。優れたドキュメントは説明するだけでなく、マーケティングの役割も果たします。利用のハードルを下げ、信頼を築き、興味を持った訪問者を、製品を他の人に勧めるアクティブユーザーへと変えます。

概要

開発者向けドキュメントには、マーケティングにおける複数の役割があります。

• 獲得：ドキュメントは検索結果に表示され、解決策を積極的に探している開発者を引きつけます
• 活性化：構成の優れたクイックスタートは、価値を実感するまでの時間を短縮します
• 継続利用：充実したリファレンスは、開発者が開発を続けるのに役立ちます
• 紹介：開発者は、気に入ったドキュメントを共有します。マーケティングページではありません

このスキルでは、テクニカルライティングと開発者向けマーケティングの接点を取り上げます。学習とコンバージョンの両方の目標に役立つドキュメントを作成します。

始める前に

developer-audience-context スキルを確認して、対象となる開発者について理解しましょう。

• どのような問題の解決策を探していますか？
• 技術的な知識のレベルはどの程度ですか？
• どのフレームワークや言語を使っていますか？
• 現在、どこで答えを探していますか？

ドキュメント戦略では、こうしたオーディエンスに関する知見に直接応える必要があります。

コンバージョンにつながる情報アーキテクチャ

ドキュメントの4つの種類

開発者が必要とする4種類のドキュメントを中心に構成しましょう。

種類	目的	マーケティング機能
チュートリアル	学習を目的とした、段階的な説明	自信を育み、製品の価値を示す
ハウツーガイド	タスクを目的とした、問題解決の説明	幅広い機能を実証する
リファレンス	情報を目的とした、正確な説明	製品の奥深さと信頼性を証明する
解説	理解を目的とした、概念的な説明	思想的リーダーシップを確立する

離脱を減らすナビゲーション

良いナビゲーション構成：

Getting Started
├── Quickstart (< 5 min)
├── Installation
└── Core Concepts

Guides
├── Authentication
├── [Most Common Use Case]
├── [Second Most Common Use Case]
└── ...

API Reference
├── Overview
├── Authentication
├── Endpoints (alphabetical or logical grouping)
└── SDKs

Resources
├── Examples
├── Changelog
└── Support

悪いナビゲーション構成：

Documentation
├── Chapter 1: Introduction
├── Chapter 2: Getting Started
├── Chapter 3: Advanced Topics
├── Appendix A
└── API (link to separate site)

情報の階層

すべてのドキュメントページは、次の階層に従う必要があります。

1. これは何ですか？（1文）
2. なぜ使うのですか？（1～2文）
3. どのように使いますか？（ページの大部分）
4. 次に何をすればよいですか？（明確な次のステップ）

クイックスタートの最適化

クイックスタートは、最も重要なコンバージョンページです。徹底的に最適化しましょう。

5分ルール

開発者が5分以内に、意義のある成功体験を得られるようにしましょう。クイックスタートにそれ以上かかる場合、開発者を逃していることになります。

測定して最適化する項目：

• ページの読み込みから最初のAPI呼び出しが成功するまでの時間
• クイックスタートのフローにおける離脱ポイント
• 完了率

クイックスタートの構成

# Quickstart

Get your first [meaningful result] in under 5 minutes.

## Prerequisites
- [Specific version] of [language/tool]
- [Account/API key] (link to signup)

## Step 1: Install
[Single command, copy-paste ready]

## Step 2: Configure
[Minimal configuration, explain what each part does]

## Step 3: Run
[The payoff—show them it works]

## What You Built
[Explain what just happened and why it matters]

## Next Steps
- [Immediate next tutorial]
- [Reference docs for what they just used]
- [Community/support link]

良いクイックスタートと悪いクイックスタート

良いクイックスタート：

# Send Your First Message

Send an SMS in under 5 minutes.

## Prerequisites
- Node.js 16 or higher
- A Twilio account ([sign up free](link))

## Install the SDK
```bash
npm install twilio

メッセージを送信する

send-sms.js を作成します。

const twilio = require('twilio');
const client = twilio('YOUR_ACCOUNT_SID', 'YOUR_AUTH_TOKEN');

client.messages.create({
  body: 'Hello from my app!',
  to: '+15551234567',
  from: '+15559876543'
}).then(message => console.log(`Sent: ${message.sid}`));

実行します。

node send-sms.js

次のように表示されます：Sent: SM1234...

何が起きたのか

API認証情報で認証し、SMSを送信しました……

**Bad Quickstart:**
```markdown
# Getting Started

Welcome to our platform! Before we begin, let's discuss
the architecture of our messaging system...

[500 words of background]

## Installation

First, ensure you have the correct version of Node.js.
You can check this by running...

[200 words on version checking]

You'll also need to configure your environment variables.
Create a .env file and add the following variables...

[Complex configuration with 10+ variables]

APIリファレンスのベストプラクティス

すべてのエンドポイントに必要な項目

1. 何をするかを説明する1文の説明
2. 明記された認証要件
3. すべてのパラメーターを文書化したリクエスト形式
4. 例を含むレスポンス形式
5. よくある原因を示したエラーレスポンス
6. 実際に動作するコピー＆ペースト可能な例

動作するコピー＆ペースト用コード

重要：サンプルコードはコピーしたときに動作しなければなりません。テストしてください。

良い例：

## Create a User

Creates a new user in your organization.

### Request
```bash
curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Jane Developer"
  }'

レスポンス

{
  "id": "usr_123abc",
  "email": "[email protected]",
  "name": "Jane Developer",
  "created_at": "2024-01-15T10:30:00Z"
}

エラー

コード	意味
400	無効なメールアドレス形式
409	メールアドレスはすでに登録されています
401	APIキーが無効、または指定されていません

**Bad Example:**
```markdown
## POST /users

Parameters:
- email (string)
- name (string)
- org_id (string, optional)
- role (enum, optional)
- metadata (object, optional)
- ...

Returns a user object.

言語別の例

開発者が実際に使用している言語で例を用意しましょう。

• cURL（汎用的なので、必ず含める）
• JavaScript/Node.js
• Python
• Go
• Ruby
• PHP
• 最もよく使われているSDKの言語

ドキュメントの検索最適化

検索順位を高めるドキュメント

開発者向けドキュメントは、購入意欲の高い検索トラフィックを獲得できます。

ターゲットとする検索クエリの種類：

1. 問題に関するクエリ：「node.js から sms を送信する方法」
2. 比較に関するクエリ：「[自社製品] vs [競合製品]」
3. 連携に関するクエリ：「[自社製品] を [人気のツール] と連携する」
4. エラーに関するクエリ：「[具体的なエラーメッセージ]」

ドキュメントの SEO の基本

ページタイトル：

Good: "Send SMS with Node.js | Twilio Docs"
Bad: "Documentation - Messaging - SMS - Send"

メタディスクリプション：

Good: "Learn how to send SMS messages using Node.js and the
Twilio API. Includes code examples and troubleshooting tips."

Bad: "This page contains documentation for the SMS sending
functionality of our messaging product."

URL 構造：

Good: /docs/sms/send-messages/nodejs
Bad: /docs/section/3/page/27?lang=nodejs

内部リンク

ドキュメントを孤立した領域にせず、ドキュメントのネットワークを作りましょう。

• 関連する概念にリンクする
• リファレンスからチュートリアルにリンクする
• チュートリアルからリファレンスにリンクする
• SDK のドキュメント間を相互にリンクする

ドキュメントの効果測定

主な指標

指標	わかること
クイックスタートの閲覧時間	エンゲージメント（ただし、混乱の度合いも示します）
クイックスタートの完了率	コンバージョンの効果
検索 → 登録率	顧客獲得チャネルとしてのドキュメントの効果
サポートチケットの削減率	ドキュメントの網羅性
ページの評価／フィードバック	コンテンツの品質
サイト内検索クエリ	コンテンツの不足箇所

フィードバックループ

実施すること：

• すべてのページに「役に立ちましたか？」を設置する
• サイト内検索を分析する（ユーザーは何を検索しているか？）
• サポートチケットを分析する（ドキュメントで回答できていない質問は何か？）
• 開発者にインタビューする（わかりにくい点は何か？不足しているものは何か？）

よくあるドキュメントのアンチパターン

「テキストの壁」

問題：コードも構成も視覚的な区切りもないページ 解決策：コードを冒頭に配置し、見出しを積極的に使い、段落を分割する

「知識を前提とする」落とし穴

問題：開発者が独自の用語を知っていると想定する 解決策：用語は初出時に定義し、用語集にリンクする

「何でも載せるページ」

問題：1 ページですべてのユースケースを扱おうとする 解決策：個別のタスクごとにページを分け、相互にリンクする

「古くなったクイックスタート」

問題：クイックスタートのコードが動かなくなっている 解決策：ドキュメント内のコードサンプルを自動テストする

「隠れた前提条件」

問題：チュートリアルの途中で要件が明らかになる 解決策：バージョン番号とともに、すべての前提条件を冒頭に記載する

ツール

ドキュメントプラットフォーム

• GitBook：小規模チームに適しており、デフォルト設定も優れています
• ReadMe：インタラクティブな API ドキュメントを作成でき、指標機能も組み込まれています
• Mintlify：モダンで高速、開発者体験にも優れています
• Docusaurus：柔軟でセルフホスト可能、React ベースです
• Notion：すぐにセットアップできますが、カスタマイズには制限があります

コードサンプルのテスト

• Doctest：ドキュメント内の Python コード
• mdx-js：Markdown 内の JSX
• カスタム CI：コードサンプルをテストとして実行する

検索と分析

• Algolia DocSearch：オープンソース向けには無料で、強力な機能を備えています
• Google Analytics：基本的なトラフィック指標
• FullStory/Hotjar：セッション録画、ヒートマップ
• サイト内検索の分析：開発者は何を検索しているか？

関連スキル

• api-onboarding：最初の API 呼び出しまでの体験全体を最適化する
• sdk-dx：ドキュメントをシンプルにする SDK を作成する
• developer-sandbox：ドキュメントを補完するインタラクティブな環境
• technical-content-strategy：ドキュメントを含む、より広範なコンテンツ戦略
• developer-audience-context：誰に向けて書いているのかを理解する