プロダクトとしてのドキュメント

Spec: ISO/IEC/IEEE 26514 Spec: ISO/IEC/IEEE 26513 Spec: ISO 24495-1 Evidence: Standard-backed

概要

これらのページは、ドキュメント品質モデルに沿って構築され、平易な言葉のベースラインと階層化されたスタイル階層のもとで執筆され、エンジンのコードに対して実行されるものと同種の自動ゲートで検証されています。このページでは、その規律と、ドキュメントの欠陥がエンジニアリング上の欠陥として記録される理由を説明します。

このページは、自信ありげなのに検証できないドキュメントで苦い経験をし、信頼する前にこのドキュメント群が何によって異なるのかを知りたいシニアエンジニアに向けて書かれています。

なぜこれが重要なのか

ドキュメントライブラリが購入されるのは信頼があるからであり、その信頼を得るか失うかはドキュメントによって決まります。誤りを検出しにくいページは、ページが存在しないよりも悪質です。慎重な判断を、見当違いの確信へと変えてしまうからです。その失敗は、あなたの名前がコミットに残ったまま本番環境で表面化します。

標準規格文書は、その代償を率直に述べています。よく設計されたユーザー情報は、サポートコストを削減するだけでなく、プロダクトとその提供者の評判を高めます。それを実現するには、検証およびバリデーションのテストを開発後ではなく、開発の中に組み込む必要があります Spec: ISO/IEC/IEEE 26513, §Foreword 。NextPDF はそれを文字どおりに受け止めています。ドキュメントは、コードに付随する礼儀ではなく、品質基準を備えたプロダクトの一面なのです。

要点

NextPDF では、これらのドキュメントを、§8 のユーザー情報基準から導かれた明示的な 情報品質モデル に沿って管理しています。つまり、ページは技術的に正確であり、一貫した一つの語彙を用い、想定された読者が理解でき、必要なことだけを述べながら求められるものを何も省かず、支援技術から到達可能でなければなりません Spec: ISO/IEC/IEEE 26514, §8 。
構造は場当たり的に決めるものではありません。トピックは メタデータを伴う凍結された階層に編成 され（セクション、対象読者、証拠レベル）、読者が見て認識し、目的のトピックを見つけられるようになっており Spec: ISO/IEC/IEEE 26514, §9 、最も重要な記述は各ページの先頭付近に置かれています Spec: ISO 24495-1, §5 。
文体は 承認済みのスタイル階層 によって統制されています。トーンは Apple、手順は Microsoft、コードは Google、そしてそのすべてにわたって平易な言葉を用いるというもので、各逸脱について、それが上書きする上流の条項とともにリポジトリ内に記録されています。
品質は 機械検証 されています。Vale が文体パックを強制適用し、一連の composer docs:* ゲートが、リンクの整合性、引用の健全性、標準規格の逐語テキストの不使用、そして非公開の詳細の漏洩がないことを強制します。
ドキュメントは コードとともに反復的に 開発されます。各変更にはそのドキュメントが伴い、後回しのバックログとしては扱いません Spec: ISO/IEC/IEEE 26515, §Introduction 。

NextPDF のアプローチ

明文化された品質モデル

「良いドキュメント」は、その属性を名指しするまで反証不可能です。NextPDF は、§8 のユーザー情報基準を NextPDF 自身の言葉で言い換え、すべての Insider_ ページを照らしてレビューする基準として用いています。各ページは技術的に正確であり、一貫した一つの語彙を保ち、対象とする読者が理解でき、その読者が必要とするものだけを含み、求められるものを何も省かず、支援技術から到達可能であり続けなければなりません Spec: ISO/IEC/IEEE 26514, §8 。これらは形容詞ではなく、レビューの基準です。「必要十分」というテストがあるからこそ、ページは水増しではなく自らの境界を述べて止まるのです。語彙の一貫性が求められるからこそ、用語は統制されます（後述）。到達可能性が基準に含まれるからこそ、すべてのコンポーネントはキーボードとスクリーンリーダーに安全であり、決して色だけで合図することはありません。

好みではなく分析による構造

Insider_ の分類体系は、どのページよりも先に凍結されています。これは意図的です。ISO 26514 は、対象読者およびタスクの分析が情報の設計に 先立つ ことを求めています Spec: ISO/IEC/IEEE 26514, §9 。また、トピックが階層またはグループに編成され、それぞれが対象読者と情報の種類を識別するメタデータを持つことで、ユーザーが必要なものを素早く見つけられることも求めています Spec: ISO/IEC/IEEE 26514, §9 。このリポジトリでは、そのメタデータは具体的なフロントマター（section、audience、evidence_level、tags）であり、クラスタマップは単一の凍結されたファイルです。読者は見て認識してページを選び、スラッグを思い出す必要は決してありません。

ページ内の順序は固定され、どのページでも同じです。最も有用な記述は、読者が最初に見つける場所、通常は冒頭に置かれます Spec: ISO 24495-1, §5 。だからこそ、すべての Insider_ ページは詳細よりも前に要点を置きます。読者は三つのセクションで読むのをやめても、なお根拠を持って説明できる答えを持ち帰れます。

裏付けを伴うスタイル階層

文体は書き手の気分に委ねられていません。リポジトリには、承認済みの上書きシート（docs/style/nextpdf-overrides.md）が含まれており、Apple（トーン）、Microsoft MSTP（手順と UI 用語）、Google DDSG（コードと CLI）を、平易な言葉と統制語彙のベースラインの上に重ね、モードごとの競合解決表を備えています。その中で最も厳格な規則は、他のすべてに優先します。つまり、ライセンス対象の標準化団体文書から逐語テキストを使わないことです。重要なのは、NextPDF が上流のガイドから逸脱するすべての箇所が、それが上書きする上流の条項とその理由とともに 記録されていることです。このスタイルシートは、ページと同じやり方で自らの出典を引用しています。

信用に頼る必要のない品質

この規律は、善意ではなくツールによって強制されています。

Scaffold The page starts from a populated front-matter and section skeleton.
Vale packs Apple, MSTP, Google, and controlled-vocabulary rules run on the prose.
Link check docs:link-check rejects link rot against the built site.
NDA scan docs:nda-scan rejects private FQCNs and internal artefact names.
Quote fingerprint docs:jaccard-fingerprint flags verbatim standards-text reuse.
Citation audit docs:rag-citation-check / docs:rag-fallback-check guard the digests.
Review A reviewer confirms the page's declared evidence level holds.

ページが通過する順序でのドキュメント品質ゲート。投入済みの足場が構造を固定し、Vale が文体パックを強制し、docs:* ゲートがリンクの整合性、引用の衛生、標準規格の逐語テキストの不使用、そして非公開の漏洩がないことを強制し、レビューが証拠の基盤を確認します。ゲートに失敗したページは欠陥であり、失敗するテストと同じように扱われます。

これらは、このリポジトリの composer.json にある実際のエントリに対応しています。docs:lint は NDA とリンクのゲートをローカルで実行します。docs:jaccard-fingerprint は、類似度しきい値を超える標準規格テキストの逐語再利用を検出します。docs:rag-fallback-check は、引用整合性プロトコルをオフラインかつ決定的に強制する、完全に実装済みのチェックです。ライブ RAG 再検証（docs:rag-citation-check）と一部のスキャナーはゲートとして配線済みですが、より深いランナーはまだ構築中です。正直に言えば、契約は承認済みで、構造的なチェックは今日すでに強制されています。一方で、すべてのチェックを網羅的にする取り組みは継続中です。Insider_ は、まだ獲得していないグリーンダッシュボードを主張しません。これは、この品質モデルの「正確」という基準をこのページ自体に適用した結果でもあります。

証拠が示すこと

このページは、ドキュメント品質に関する主張については Evidence: Standard-backed であり、強制に関する主張についてはリポジトリ内の根拠に基づいています。この二重の根拠は意図的です。原則は標準規格に由来し、強制はリポジトリを読むことで検証できます。

主張	根拠	アンカー
ドキュメントには定義済みの品質基準がある	標準規格	正確、単一語彙、読者が理解可能、必要十分、支援技術から到達可能 Spec: ISO/IEC/IEEE 26514, §8
用語は統制されている	標準規格	情報セット全体で一貫した用語 Spec: ISO/IEC/IEEE 26514, §8
構造は執筆に先立つ	標準規格	設計前の対象読者分析とタスク分析 Spec: ISO/IEC/IEEE 26514, §9
最も有用な記述は先に置かれる	標準規格	冒頭に置かれる最も重要なメッセージ Spec: ISO 24495-1, §5
ドキュメントはコードとともに出荷される	標準規格	各反復の成果物にユーザー情報が含まれる Spec: ISO/IEC/IEEE 26515, §Introduction
品質は機械検証される	リポジトリ内	`composer.jsondocs:*` ゲート、批准された `docs/style/nextpdf-overrides.md`、有効な Vale 設定

実践例

この規律は最小のスケールにも現れます。品質に関する数値は決して本文に手入力されません。本文内の数値は、静かに陳腐化するからです。それは 値をでっち上げることを拒む コンポーネントによってレンダリングされ、ページの証拠基盤によって裏付けられています。

<?php

declare(strict_types=1);

// Illustrative: the documentation build's contract for a quality datum.
// The component throws if no real value is supplied — a metric is never
// allowed to live as a hardcoded literal that can drift out of date.
final class QualityDatum
{
    public function __construct(
        public readonly string $label,
        public readonly string $value,
    ) {
        if ($this->value === '') {
            throw new \InvalidArgumentException(
                'A quality datum must carry a verified value; '
                . 'documentation never invents a metric.',
            );
        }
    }
}

$phpstanLevel = new QualityDatum(label: 'PHPStan', value: 'Level 10');

要点は throw にあります。情報品質モデルの「正確」という基準は、ここでは助言ではありません。陳腐化した数値が静かに出荷されないよう、構造的に強制されています。

よくある誤解

陥りやすいのは、「プロダクトとしてのドキュメント」を、磨き上げ、つまりより美しい本文やより見栄えの良いページについてのスローガンとして読むことです。それは表面的なものの正反対です。これは、ドキュメントが定められた品質基準、統制された語彙、凍結された構造、そして機械検証されたゲートを備えており、そのいずれかに失敗したページは 修正を伴う欠陥 であって、失敗するテストと同じように扱われることを意味します。磨き上げはこの規律の副産物であって、その目的ではありません。

二つ目の落とし穴は、契約が存在するからといって、すべてのゲートがすでに網羅的だと思い込むことです。そうではありません。そしてこのページはそれをはっきり述べています。構造的なチェックは今日すでに強制されていますが、より深い検証ツールは構築途上にあります。そうでないと主張することは、このページが説明しているまさにその品質モデルに違反することになります。

限界と境界

このページはドキュメントの規律を説明します。スタイルシートでも、分類体系のファイルでも、ゲートの実装そのものでもありません。エンジンの挙動については何も主張しません。権威ある成果物はリポジトリ内にあり（docs/style/nextpdf-overrides.md、凍結された分類体系、composer.json の docs:* スクリプト）、ここでの要約と食い違う場合はそれらが優先されます。

強制の範囲は、正直に言って部分的です。引用整合性のフォールバックチェックは稼働しています。リンクと NDA のゲートはローカルで実行されます。逐語引用とライブ引用の検証ツールは配線済みですが、その網羅的なランナーはまだ着地途上です。これは完了ではなく進行中として報告されます。このページが Premium ティアのドキュメントに触れる箇所では、説明されている規律はプロセスのレベルで適用され、いかなる非公開のメカニズムのレベルにも及びません。

用語集

情報品質モデル — NextPDF による ISO 26514 §8 のユーザー情報基準（正確、単一語彙、読者が理解可能、必要十分、支援技術から到達可能）の言い換えであり、すべての Insider_ ページのレビュー基準として用いられます。
平易な言葉 — 想定された読者が内容を見つけ、理解し、使えるようにする言い回し、構造、デザインを備えたコミュニケーション。コンテンツの一種ではなく、すべてのモードに適用されるベースライン。
スタイル階層 — 承認済みで階層化された上流のスタイルガイド一式（Apple、Microsoft、Google に加え、平易な言葉と統制語彙のベースライン）であり、NextPDF のあらゆる逸脱がその出典に対して記録されています。
品質ゲート — ページが通過しなければならない自動チェック（Vale パックまたは composer docs:* スクリプト）。失敗は些細な指摘ではなく、ドキュメントの欠陥です。
フロントマターのメタデータ — ページを所在特定可能かつ分類可能にする機械可読なヘッダー（section、audience、evidence_level、tags）であり、トピック編成の要件に従います。