ja-doc-profile

文書の種類と読み手を、何を手がかりにどの順で決めるか、いつ利用者に尋ねるか、決まらないときどうするかを持つ。tanteki と yomiyasu は種類の分け方が違うので、二つの対応も持つ。種類の名前と値を持つのは各入口で、ここでは意味と使い方だけを決める。値は書き換えない。

対象と範囲

• 読むのは、種類と読み手を判定する入口の tanteki と yomiyasu である。
• koncise は読み手が ADHD の人に固定されており、japanese-tech-writing は技術書と記事の読者に固定されている。どちらも読まない。
• 種類ごとに書くべきこと、直さない普通の書き方、長さ、lint で外す規則は、種類の一覧の側にある。ここでは扱わない。

判定の材料と順

• 利用者の指定、依頼の行き先や宛先、本文の形の順に見る。指定と本文の形が食い違うときは指定に従う。
• 依頼の行き先から決めたものは、指定ではなく推定として扱う。
• 本文が説明なしに略語を使っていても、そこから読み手を決めない。書き手の想定は分かるが、読む人の知識は分からない。
• 「技術記事向け」のような分野の名前だけでは、種類も立場も決めない。文書の立場（勧め、決まり、説明）は、種類から導かない。
• 推定で決めてよいのは、次のときだけである。
  • 種類: 依頼の行き先か宛先が 1 つの種類を示し、本文にほかの種類の手がかりがない。または、本文に 1 つの種類の手がかりが 2 つ以上あり、ほかの種類の手がかりがない
  • 読み手: 依頼か宛先が読み手を示す。または、入口が種類ごとに既定の読み手を持ち、依頼と本文にそれと食い違う手がかりがない
• 1 つの文書が 2 つの種類にまたがるとき（台本つきのスライド、提案を含む議事録）は、主な種類が 1 つに決まればそれにし、決まらなければ決めない。
• どれにも当たらなければ、決めない。
• yomiyasu の種類ごとの手がかりの表は ../yomiyasu/references/audience.md にある。表に当たるかどうかは入口が判定の後に読む。

読み手の段階

yomiyasu の READER_LEVELS の値は 3 つである。

• expert: 同じ分野の専門家。用語の説明を必要としない。
• informed: 分野は違うが技術に詳しい人。技術以外の文書では、その文書の話題に通じた人として読む。
• general: 専門知識のない人。

宛先から当てるときの目安は次のとおり。

• 「全社員向け」「顧客向け」は general
• 同じチームの開発者やレビュアー宛ては expert
• 「上長に」は informed
• 書き手との関係が指定されたときは、../yomiyasu/references/persona.md の関係と段階の目安の表を使ってよい。関係を推定しただけのときは関係を使わず、ほかの手がかりだけで決める

「初学者向け」のような読者像も 3 つのどれかに当てる。当てられなければ決めない。tanteki は読み手を自由な文で書く。その読み手を段階に当てるのは、用語の説明の要否を決めるときだけである。

尋ねるか

書く前に利用者へ尋ねるのは、次の両方を満たすときだけで、尋ねるのは 1 回に限る。

• (a) 種類か読み手が決まらないと、本文の構成か用語の説明が変わる
• (b) 利用者が答えを知っている見込みがある（宛先、目的、提出先を利用者が持っている）

例を二つ挙げる。

• 「上の人に出す資料を直して」: 上の人が役員か隣のチームかで用語の説明が変わり、利用者は知っている。尋ねる
• 「この手順を読みやすく」: 手順の並びから種類が決まる。尋ねない

(a) と (b) を満たしても、次の場面では尋ねない。

• 本文だけを返すよう指定された
• ほかのスキルの途中で呼ばれた
• 利用者が「確かめずに」「おまかせで」「質問しないで」と頼んだ
• 一回きりの実行である（claude -p、codex exec、CI、フック。返事を待てないことが依頼かホストから分かるとき。分からなければ尋ねられるものとする）
• 同じ依頼の中ですでに 1 回尋ねた（複数の原稿をまとめて直す依頼でも 1 回だけ）

尋ねないときは入口の既定に従う。

• tanteki: 最も近い種類に決める
• yomiyasu: 種類を決めない

tanteki は、種類を決めたら、尋ねたかどうかによらず、作業メモに 種類: <tanteki の種類> の 1 行を書く。区分と読み手はこの行に混ぜず、別の行に書く。

用語の説明

• 用語を説明するかどうかは、読み手の段階で決める。expert には足さず、informed と general には要る。
• 説明の中身の出どころは、../ja-fact-preservation/SKILL.md の「足さないこと」に従う。
• 原文にも資料にも説明が無いときは、入口の決まりに従う。yomiyasu は「ここに説明が必要です」の印を置き、tanteki は確かめたい点に出す。
• 関係が社外でも、段階が expert なら説明は要らない。決めるのは関係でなく段階である。

対応表

左は tanteki の種類（../tanteki/references/document-types.md と ../tanteki/references/types/ の見出しの名前）、右は yomiyasu の DOC_TYPES の値で書く。

• インシデント記録、ポストモーテム → incident

• 会議メモ/決定ログ → minutes

• 運用 Runbook、操作/利用ガイド、チュートリアル、受け入れテスト手順書 → manual。障害時の対応手順も、手順の並びなら manual。起きた障害の記録は incident

• 要求仕様、ユーザーストーリー、ユースケース、機能仕様、非機能要求、API 仕様、データ/イベント仕様 → 条項番号があるか、「〜しなければならない」「〜とする」の規範の文が中心なら formal。なければ種類なし

• Design Doc、RFC/技術提案、ADR、セキュリティ設計/脅威モデル、データモデル設計、UI 振る舞い仕様 → 種類なし。分野は tech。本文が方式の比較、構成、データの流れなら、背景や目的の見出しがあっても proposal にしない

• ビジョン・戦略、製品企画の概要（Product Brief）、PRD → 承認か選択を依頼する節があれば proposal。なければ種類なし

• プロジェクト計画、進捗/status report、廃止/移行告知、テスト計画、テスト結果、リリース/ロールアウト計画、データ移行計画、変更履歴（Release Notes）、ロードマップ → 種類なし。週報とリリースノートを種類なしとする yomiyasu の例と同じ

• 技術調査の報告（Spike）、問題定義、顧客調査計画、顧客調査結果、分析結果・意思決定用メモ、実験計画、環境調査・検証記録 → 種類なし。paper にしない

• README、FAQ/トラブルシュート、確認依頼、SLI/SLO 方針 → 種類なし。本文が手順の並びなら manual、条項番号と規範の文が中心なら formal。本文から決める

• 種類なしのときは、種類の表と種類の資料を使わず、分野が分かれば分野の資料だけを使う。

• yomiyasu の pr、article、essay、promo、mail、paper、slides には、tanteki の種類が無い。tanteki は業務・技術文書だけを扱う。

• 手がかりの表で「仕様書」の語に当たっても、規範の文が中心でなければ formal にしない。

種類ごとの一覧の置き場

判定の後に、入口が次を読む。

• 種類ごとに書くべきこと: ../tanteki/references/types/
• 直さない普通の書き方、それでも直すもの、長さ: ../yomiyasu/references/doc-types/
• 分野ごとの扱い: ../yomiyasu/references/domains/

参考

判定の規則は次の上流のスキルを読んで振り分け、自分の言葉で書き直した。

• tanteki の上流: iwasa-kosui/tanteki の skills/tanteki、commit e9c4ae749fbe1b35cb740d9e7e0e00a00a0cb42b。Copyright (c) 2026 Kosui Iwasa（MIT）
• yomiyasu の上流: nanaism/yomiyasu の skills/yomiyasu、commit 79d15a621751cb7ad3bea556832209e9112e575f。Copyright (c) 2026 nanaism（MIT）