diataxis-writer

Diataxis ライター

Diataxis を活用して、ドキュメントを読者の実際のニーズに合わせます。このフレームワークは単なるテンプレート集ではありません。性質の異なる4つのユーザーニーズが、わかりにくい1つのドキュメントに混在するのを防ぐ方法です。

ユーザーへの Diataxis の説明

ユーザーから Diataxis とは何か、なぜ重要なのか、なぜこのフレームワークが適しているのかを尋ねられたら、適用する前に簡潔に説明します。

Diataxis は、読者の作業モード（学ぶ、実行する、情報を調べる、概念を理解する）に応じてドキュメントを分けるフレームワークです。読者はそれぞれ異なる期待を持ってドキュメントを参照するため、これは重要です。チュートリアルに沿って学ぶ初心者には導かれた道筋が必要です。実稼働環境の問題を解決する運用担当者には、直接的な手順が必要です。API を確認する開発者には、正確なリファレンスが必要です。アーキテクチャ上の判断を行うチームには、説明とトレードオフの情報が必要です。こうしたニーズを1つのページに混在させると、ドキュメントは長く、わかりにくく、保守しづらくなります。

Diataxis を推奨する際は、次の利点を伝えてください。

• 執筆を始める前に、各ドキュメントの目的が明確になります。
• 学習、タスクの実行、情報の検索、概念の理解を分けることで、肥大化した「すべてを詰め込んだページ」を減らせます。
• 構成が読者の目標に合うため、読者の体験が向上します。
• 各ページの役割と担当範囲が明確になり、ドキュメント群を保守しやすくなります。
• 学ぶ、実行する、調べる、理解するといった目的で人を支援するコンテンツであれば、技術ドキュメントに限らず、ナレッジベース、オンボーディング資料、社内プロセスのドキュメント、マニュアル、運用ガイドにも活用できます。

Diataxis があらゆる状況に適していると誇張してはいけません。ユーザーが明示的に Diataxis に基づく批評を求めている場合を除き、マーケティングページ、営業提案書、プレスリリース、法的契約書、小説など、説得を主目的とする文章にはあまり適していません。

コアモデル

読者の意図に基づいてドキュメントを分類します。

読者のニーズ	Diataxis の種類	ドキュメントが約束すること
実践を通じて学ぶ	チュートリアル	「この道筋に沿って進めば、基本的な能力が身につきます。」
タスクを完了する	ハウツーガイド	「これらの手順に従えば、この成果を達成できます。」
情報を調べる	リファレンス	「正確で完全な情報をすばやく見つけられます。」
背景を理解する	解説	「なぜそのように動作するのかを理解できます。」

ユーザーが詳しいテンプレート、変換パターン、例を求めた場合は、references/diataxis-patterns.md を参照してください。

ワークフロー

1. 読者の目的を特定します。 読者が学ぼうとしているのか、作業しようとしているのか、情報を調べようとしているのか、理解しようとしているのかを判断します。依頼が曖昧な場合は、最も可能性の高い分類を示して進めます。ただし、誤った分類を選ぶと成果物全体が変わる場合は除きます。
2. 対象読者と範囲を定めます。 読者のレベル、製品やプロセスの背景、期待する成果、制約を把握します。執筆中はこれらを意識し続けます。
3. 主要なドキュメントの種類を1つ選びます。 主要な種類に構成、トーン、詳しさを合わせます。他の種類に属する補足資料は、短い「関連情報」セクションに移すか、別のドキュメントにします。
4. 目的に沿って執筆または再構成します。 以下の種類ごとのガイダンスに従います。情報に関連性があるというだけで、チュートリアル、ハウツー、リファレンス、解説を1ページに混在させないでください。
5. 成果物を確認します。 各セクションが主要な読者の目的に役立つかを確認します。別の目的に役立つセクションは削除するか、別の場所に移します。
6. 文章を推敲します。 成果物に自分で執筆または書き直した文章が含まれる場合にのみ、この手順を実行します。分類メモ、構成案のレビュー、書き直した文章を含まない書き換え計画では省略します。最後に実行します。まず構成を整え、次に文章を整えます。
   • このセッションで humanizer という名前のスキルを利用できる場合は、完成したドキュメントに対して実行し、最終テキストのみを返すよう依頼します。humanizer はこれを埋め込みモードと呼びます。種類ごとの語り口を保てるよう、Diataxis の種類を伝えます。チュートリアルでは導く口調、ハウツーでは命令形、リファレンスでは中立的な口調、解説では選択肢を比較検討する口調にします。文章のみを変更します。見出し、セクションの順序、コード、コマンド、表、リンク先は変更しません。
   • 利用できない場合は、Reader-First Prose のルールと references/ai-prose-tells.md のチェックリストを適用します。その後、この会話中に一度だけ、npx skills add blader/humanizer で完全版のスキルをインストールできることをユーザーに伝えます。この提案を繰り返さないでください。
   • Simplified Technical English が適用される場合は、humanizer による処理後に references/ste-rules.md に照らしてテキストを確認します。STE は最後に適用します。

読者優先の文章

形式や文学的な流れより、理解しやすさを重視して書きます。

• 1文で伝える主な考えは1つにします。
• 文章の1文は、8～20語を目安にします。
• 25語を超える文はすべて見直します。正確さが損なわれたり、考え同士の関係が分かりにくくなったりしない限り、文を分割します。
• 簡潔な文を優先します。従属節は、必要な条件、原因、対比、限定を、2つの独立した文より明確に伝える場合にのみ使います。
• 入れ子になった従属節や、節が3つ以上ある文は避けます。
• 補足的な詳細は、新しい文、リスト、注記、またはリンク先のドキュメントに移します。
• 専門用語、契約、制約、根拠、重要な例外を維持します。簡潔さのために必要な意味を削らないでください。
• 各主張の確実性を保ちます。「失敗する可能性がある」を「失敗する」に変えないでください。原文にない原因、頻度、事実を追加しないでください。
• 1つの概念には1つの用語を使います。同じ操作に対して「確認」「検証」「確かめる」などの類義語を使い分けないでください。
• 名詞の連結は3語以内にします。
• 各段落では1つのテーマを扱い、文は最大6つにします。手順や条件が3つ以上ある場合はリストを使います。
• コード、コマンド、パス、表、見出し、引用、生成された識別子には、文の長さの制限を適用しません。
• 文の長さに自然な変化をつけます。すべての文を同じ短いパターンにしないでください。Simplified Technical English が適用されるテキストは例外です。

語数は、機械的な合否判定ではなく、見直しの目安として扱います。ベトナム語では、スペースで区切られたトークンが語に対応するとは限りませんが、一貫してトークンを数えます。語をスペースで区切らない言語では、1文1主題と節の数のルールに従います。

Simplified Technical English

ASD-STE100 Simplified Technical English（STE）は、技術文書の意味を一つに限定するための制御言語です。言語に依存しないルールは、すでに Reader-First Prose と「手順ガイド」に記載されています。英語固有のルールは references/ste-rules.md に記載されています。

このファイルを読み、出力が英語で、次のいずれかに該当する場合に適用してください。

• ページが手順ガイドまたはリファレンスページである場合、またはテキストがチュートリアルの手順、警告、エラーメッセージである場合、あるいは
• ユーザーが STE、ASD-STE100、Simplified Technical English、または制御言語への書き換えを依頼した場合。

英語固有のルールを他の言語に適用しないでください。出力が STE に準拠しているとは述べないでください。公式の STE 辞書は含まれていないため、出力は STE スタイルです。

種別に関するガイダンス

チュートリアル

読者に段階的な学習体験が必要な場合は、チュートリアルを使用してください。

• 読者がゼロから具体的な結果に到達できる、安全で再現可能な手順を示します。
• 選択肢の一覧よりも、信頼できる一つの方法を優先します。
• 学習者が状況を把握できるだけの説明を加えます。ただし、詳しい理論や網羅的なリファレンス資料で学習を中断させないでください。
• チェックポイント、期待される出力、復旧方法を示し、成功を確認できるようにします。
• 関連する概念を学ぶ前に、読者が専門家の判断を下せると想定しないでください。

手順ガイド

読者がすでに背景知識を持ち、作業を完了したい場合は、手順ガイドを使用してください。

• まず、得られる結果、前提条件、ガイドを使用する場面を示します。
• ユーザーが実行する順序で、行動を促す手順を書きます。
• 各手順では一つの操作を示します。能動態を使い、誰が操作するかを明記します。
• 警告や注意事項は、コマンドまたは条件から始め、その後に理由を示します。
• 判断が必要な箇所、警告、ロールバックや復旧のガイダンス、検証方法を含めます。
• 概念的な背景説明は簡潔にします。「なぜ」の説明が作業の完了を妨げる場合は、解説へのリンクを追加します。
• ガイドを初心者向けのレッスンにしないでください。

リファレンス

読者が正確な情報を参照する必要がある場合は、リファレンスを使用してください。

• コマンド、フィールド、エンドポイント、オプション、状態、エラー、スキーマ、コンポーネント、ポリシー、用語集の用語など、対象の自然な構造に沿って整理します。
• 網羅的で一貫性があり、予測しやすい内容にします。リファレンスを使う読者は情報を素早く探すため、話の導入は不要です。
• 表、シグネチャ、例、デフォルト値、制限、相互参照を使用します。
• 解釈は最小限にします。根拠の説明が必要な場合は、解説へのリンクを追加します。

解説

読者に理解、背景、根拠が必要な場合は、解説を使用してください。

• 概念、メンタルモデル、設計上の判断、トレードオフ、歴史、結果を説明します。
• 手順よりも、明快な文章、図、比較、例を優先します。
• 選択肢が複数ある理由と、特定の選択肢を採用した理由を示します。
• 作業の完了を約束しないでください。読者に手順が必要な場合は、手順ガイドへのリンクを追加します。

複合ドキュメント

実際のドキュメント一式では、4 種類すべてが必要になることがよくあります。ただし、1 つのページには、引き続き主要な目的を一つだけ持たせてください。ページに複数の種別が混在する場合は、次の手順を実行します。

1. 読者の主要なニーズを明確にします。
2. 関連性のない内容を別ページに移すか、明確に区分したセクションに分けます。
3. 学習から作業へ、作業から参照へ、参照から理解へと読者が移動できるよう、各ページへのリンクを追加します。

次のような分割方法が有効です。

• 長い「はじめに」ページは、多くの場合、チュートリアルとリファレンスページに分けられます。
• トラブルシューティングの記事は、多くの場合、手順ガイドと根本的な障害モードの解説に分けられます。
• 製品の概要は、多くの場合、解説とタスク別の手順ガイドに分けられます。
• API ドキュメントは、多くの場合、独立したチュートリアルと手順ガイドを備えたリファレンスページに分けられます。

ヘルパースクリプト

既存のドキュメントをレビューする際は、簡易的な判断基準として分類ツールを使用してください。編集上の判断に代わるものではありませんが、複数の種別が混在する兆候をすばやく見つけるのに役立ちます。

スキルのディレクトリから実行します。

bash ./scripts/classify-doc.sh path/to/doc.md

標準入力も受け付けます。

cat path/to/doc.md | bash ./scripts/classify-doc.sh

出力形式

新しいドキュメントを作成する場合は、次の内容を返してください。

1. 簡潔な分類メモ：ドキュメントの種類、読者の目的、主要な前提。
2. ドキュメント本文。
3. レビュー、再構成、または重要度の高いナレッジベースに関する作業の場合は、簡潔な確認チェックリスト。

既存のドキュメントをレビューする場合は、次の内容を返してください。

1. 現在の主な Diataxis タイプ。
2. タイプが混在している場合の問題点と、セクション単位の具体例。
3. 推奨する目標構成。
4. ユーザーの依頼に応じた、具体的な書き換え計画または書き換えたセクション。

humanizer スキルを実行した場合は、ドキュメント内にその最終テキストのみを含めてください。下書きや、残っているパターンの一覧は含めないでください。分類メモ、ドキュメント、チェックリストは上記の説明どおりに含めてください。

品質チェックリスト

• ページの主な読者の目的が1つに定まっています。
• タイトルと冒頭で、その読者の目的に合った内容を示しています。
• チュートリアルでは、すべてを先に説明するのではなく、実際に作業しながら学べるようになっています。
• ハウツーでは、寄り道せずに、十分な知識のある読者がタスクを完了できるようになっています。
• リファレンスでは、必要な情報がすべてそろい、見つけやすく、一貫した構成になっています。
• 解説では、手順であるかのように装わず、理解を深められるようになっています。
• 関連していても異なる内容は、混在させず、リンクでつなぐか、分けています。
• ユーザーから別の指定がない限り、出力言語はユーザーの言語に一致しています。
• ほとんどの文章が、主な節を1つ、主旨を1つに絞っています。
• 25語を超える文章は見直され、長さが必要なものだけが残っています。
• 条件を重ねて複雑にした文章はありません。別々に述べられる条件は分けています。
• 簡潔さを優先するあまり、契約、制約、根拠、例外を削っていません。
• 各主張の確実性は原文どおりで、新しい事実を追加していません。
• 英語のハウツー、リファレンス、チュートリアルの手順は、references/ste-rules.md に従っています。
• humanizer スキル、または references/ai-prose-tells.md を使って、AI 文章にありがちなパターンがないか確認しています。