qe-technical-writing

テクニカルライティング

<default_to_action> テクニカルコンテンツを書くときは、次の点を意識してください。

1. 価値から始める（読者は何を学び、何を得られるか）
2. 説明するのではなく、示す（具体例、コード、数値を使う）
3. ざっと読める構成にする（見出し、太字、短い段落）
4. 徹底的に削る（すべての文に存在価値を持たせる）
5. トレードオフについて正直に伝える

ブログ記事の構成：

# Title (specific promise)

## Opening (2-3 paragraphs)
- Hook: The problem or insight
- Context: Why this matters
- Promise: What they'll learn

## Body (3-5 sections)
- One clear idea per section
- Support with examples/code/data

## Closing
- Key takeaway (1-2 sentences)
- Action reader can take

改善前／改善後： ❌「包括的なテスト戦略を導入しました……」 ✅「探索的テストをスプリント計画に組み込みました。ストーリーの詳細化では、QE が開発者とペアを組むようになりました。」 </default_to_action>

クイックリファレンスカード

基本原則

原則	悪い例	良い例
価値から始める	「今日の状況では……」	「バグを 60％ 削減した方法をご紹介します」
説明するのではなく、示す	「テストを改善しました」	「スプリントあたりのバグ検出数：12→47 件」
具体的に書く	「パフォーマンスが向上しました」	「応答時間：2.3 秒→180 ミリ秒」
トレードオフを正直に伝える	「このアプローチが最善です」	「TDD により開発速度は 20％ 低下しましたが、バグは 75％ 減りました」

削るべき言葉

削る言葉	理由
基本的に、実際には、おそらく	曖昧にする言葉
活用する、相乗効果、パラダイム	企業用語
とても、本当に、かなり	不要な程度の強調
注目すべき点として	そのまま述べればよい

---

読者に合わせた文章の書き方

開発者向け

• コードまたは具体的な課題から始める
• 実装の詳細を示す
• トレードオフや代替案を説明する
• リポジトリや例へのリンクを追加する

QA／QE 向け

• テスト上の課題から始める
• ツールだけでなく、戦略を示す
• リスク評価を含める
• 応用できるヒューリスティックを提示する

リーダー向け

• ビジネスへの影響から始める
• 重要な指標を使う
• 技術的な内容を成果につなげる
• 技術的な詳細は簡潔にまとめる

---

編集チェックリスト

公開前に確認してください。

• タイトルで具体的な内容を約束している
• 冒頭で 30 秒以内に読者の関心を引く
• 主張を例で裏付けている
• 不要な言葉をすべて削っている
• コード例をテストし、正しさを確認している
• 要点が明確である
• 尊敬する同僚に送りたいと思える

---

書き換え例

改善前： 「開発ライフサイクルの早い段階でバグを発見できるよう、より包括的なテスト戦略を導入することにしました。」

改善後： 「探索的テストをスプリント計画に組み込みました。ストーリーの詳細化では、QE が開発者とペアを組み、コードを書く前にリスクを特定します。」

---

改善前： 「このアプローチには、品質向上、フィードバックサイクルの短縮、チームの連携強化など、多くの利点があります。」

改善後： 「成果は 3 つあります。平均して 2 日早くバグを発見できるようになり、リグレッションの問題が 30％ 減り、設計段階で開発者が QE に意見を求めるようになりました。」

---

エージェントとの連携

// Generate documentation from code
const docs = await Task("Generate Docs", {
  source: 'src/services/PaymentService.ts',
  format: 'markdown',
  includeExamples: true
}, "qe-quality-analyzer");

// Review documentation quality
const review = await Task("Review Docs", {
  files: ['README.md', 'docs/api.md'],
  checkClarity: true,
  checkCodeExamples: true
}, "qe-quality-analyzer");

---

エージェントの連携に関するヒント

メモリの名前空間

aqe/technical-writing/
├── generated-docs/*   - Auto-generated documentation
├── reviews/*          - Documentation review findings
└── templates/*        - Reusable doc templates

フリートの連携

const docsFleet = await FleetManager.coordinate({
  strategy: 'documentation',
  agents: [
    'qe-quality-analyzer',         // Generate and review
    'qe-api-contract-validator'    // API doc accuracy
  ],
  topology: 'sequential'
});

---

関連スキル

• bug-reporting-excellence - 技術的なバグ報告の書き方
• code-review-quality - レビューのドキュメント作成

---

覚えておくこと

人を感心させるために書くのではありません。 自分が解決した問題を、ほかの人が解決できるように書くのです。自分がいてほしかったと思う同僚のように振る舞いましょう。

経験に基づいて書きましょう。 本番環境で実際に行ったことだけを書いてください。調査中なら、そのように明記してください。