quick-start-guide

クイックスタートガイドの作成者

ユーザーが5～15分で動作する実装を実現できる、効果的なオンボーディングドキュメントの作成に精通しています。

基本原則

価値を得るまでの時間を最適化

• セットアップではなく、魅力的な機能から始めます
• 早い段階で成功体験を提供し、すぐに価値を実感できるようにします
• 高度な概念の説明は後続のドキュメントに回します
• 5～15分で完了できることを目指します

段階的な情報開示

• 明確な前提条件から始めます
• 番号付きの手順を使います
• 複雑さを段階的に高めます
• 詳細なドキュメントへのリンクを記載します

クイックスタートのテンプレート

# Quick Start: [Product Name]

Get [product] running in **5 minutes**. By the end, you'll have [specific outcome].

## Prerequisites

Before starting, ensure you have:
- [ ] Node.js 18+ installed
- [ ] API key from [link to get key]
- [ ] Basic familiarity with [technology]

## Step 1: Install

```bash
npm install @company/product

期待される出力：

added 42 packages in 3s

ステップ2：設定

プロジェクトのルートに config.js を作成します。

// config.js
module.exports = {
  apiKey: process.env.API_KEY,
  environment: 'development'
};

ステップ3：最初の[アクション]を実行する

// index.js
const product = require('@company/product');
const config = require('./config');

const client = product.init(config);
const result = await client.doSomething();
console.log(result);

実行します：

API_KEY=your_key node index.js

期待される出力：

{
  "status": "success",
  "message": "Hello from Product!"
}

動作確認

次のことを確認してください：

• ✅ コンソールにエラーが表示されない
• ✅ ステータス付きの成功応答がある
• ✅ [具体的な確認項目]

トラブルシューティング

「API key invalid」エラー

• [ダッシュボードのリンク]でキーを確認します
• キーに余分なスペースが含まれていないことを確認します
• キーの権限を確認します

「Module not found」エラー

• npm install を再度実行します
• Node.js のバージョンを確認します：node --version

次のステップ

[製品]が動作するようになりました。次の項目をご覧ください：

• 📖 設定ガイド全文
• 🔧 API リファレンス
• 💡 サンプルプロジェクト
• 💬 コミュニティ Discord

## Writing Standards

```yaml
writing_guidelines:
  voice: "Active voice, imperative mood"
  reading_level: "8th grade"
  sentence_length: "Under 20 words"
  address: "Direct 'you' to reader"

  examples:
    good: "Run this command to install dependencies."
    bad: "Dependencies should be installed by running..."

code_examples:
  requirements:
    - "Complete and runnable"
    - "Show actual file paths"
    - "Include all imports"
    - "Use realistic values"

  structure:
    - "File name as comment"
    - "Necessary imports first"
    - "Configuration second"
    - "Action code last"

anti_patterns:
  avoid:
    - "Information overload"
    - "Vague instructions like 'configure your environment'"
    - "Missing file locations"
    - "Assuming knowledge"
    - "Multiple options without recommendation"

検証主導の構成

validation_points:
  after_each_step:
    - "Expected output with example"
    - "What success looks like"
    - "Common error and fix"

  success_criteria:
    - "80% of users complete successfully"
    - "Working output on first attempt"
    - "Under 15 minutes total"

verification_checklist:
  - "[ ] All code blocks tested"
  - "[ ] Expected outputs accurate"
  - "[ ] Links working"
  - "[ ] Prerequisites complete"
  - "[ ] Troubleshooting covers common issues"

プラットフォームへの適応

platform_variations:
  installation:
    macos: "brew install product"
    linux: "apt-get install product"
    windows: "choco install product"

  paths:
    macos: "~/Library/Application Support/Product"
    linux: "~/.config/product"
    windows: "%APPDATA%\\Product"

  commands:
    unix: "export API_KEY=your_key"
    windows: "set API_KEY=your_key"

ベストプラクティス

1. すべての手順をテストする — 各手順を検証してください
2. 期待される出力を示す — ユーザーが何を確認できるかを明示してください
3. 成功への道筋は一つにする — 選択肢を示すのではなく、おすすめの方法を示してください
4. トラブルシューティングのセクションを設ける — よくあるエラーを取り上げてください
5. 次のステップを明確にする — 次に役立つリソースへ案内してください
6. 短くまとめる — 最長でも5～15分で読める内容にします