View source for Template/Doc Calibration Pattern

{{Development Notice
|status = Active Development
}}


'''Canonical Question:''' How should a template and its documentation subpage be structured so they're calibrated as one unit, not two independently-maintained pages that can drift apart?

= Template/Doc Calibration Pattern =

This page documents the working pattern developed and tested on [[Template:New Page Seed]] and [[Template:New Page Seed/doc]] — use it as the reference for building any future template/doc pair.

{{GameModule
| type = Meta & Framework
| category = [[:Category:Site Maintenance|Site Maintenance]]
| Functional Layer = Maintenance
| Application Layer = Framework Infrastructure
| Version = 0.1
| Maturity = Experimental
| Last Updated = 
| description = The reference pattern for how a template and its /doc page should be structured and calibrated together as one unit, developed and tested on Template:New Page Seed.
}}

== Core Principle ==

'''A template and its /doc page are not calibrated separately.''' The template holds the single, real Admin Page Status block. The doc page holds documentation content only, plus a plain link back to the template — it does not maintain its own independent status.

== What Goes on the Template ==

'''This list covers what's universal to every template/doc pair. It is not exhaustive — a template with unique functional behavior may need additional, page-specific sections beyond these.'''

* The actual <code><nowiki>{{Admin Page Status}}</nowiki></code> block — the single source of calibration truth.
* A live Cargo query displaying that same status, for visibility without needing to open source code: `{{#cargo_query: tables=AdminPageStatus |fields=_pageName=Page, Has_instrument_grade=Instrument Grade, Has_validation_level=Validation, Last_reviewed=Last Reviewed, Has_drift_report_status=Drift Status |where=_pageName="Template:[Exact Page Name]" |format=table |limit=1 }}` — `limit=1` is required, not optional, since duplicate stored rows are a real, confirmed possibility (see Development Breadcrumb below).
* Diagnostic/navigation templates that help someone '''working on''' this template catch real problems: <code><nowiki>{{AllTemplates}}</nowiki></code> (Template: namespace only), <code><nowiki>{{RelatedPages}}</nowiki></code>, <code><nowiki>{{Calibration Dependent}}</nowiki></code>, <code><nowiki>{{Calibration Dependencies Display}}</nowiki></code>.
* A plain link to the doc page: <code><nowiki>'''Full documentation:''' [[Template:X/doc]]</nowiki></code>.

'''Exceptions — page-specific additions:''' if a template has behavior no other template shares (e.g. a live demonstration of its own output, a unique query result relevant only to how that template functions, a setup step specific to its mechanism), that content belongs on the template too, added as its own clearly-labeled section — '''not''' omitted just because it doesn't appear in the universal list above. State plainly why it's there, the same way this whole pattern states its own reasoning, so a future reader can tell "unique and intentional" apart from "accidentally added."

== What Goes on the Doc Page ==

* All actual documentation content — usage, field guides, examples, warnings.
* A plain pointer back to the template for calibration status: '''"Calibration status for this documentation is tracked on [[Template:X]], not here."''' No query, no duplicate Admin Page Status block.
* Universal reference templates that don't help catch page-specific problems: <code><nowiki>{{Framework Reference}}</nowiki></code>, <code><nowiki>{{Calibration Procedure Reference}}</nowiki></code>, <code><nowiki>{{Calibration Maintenance}}</nowiki></code>.

== Why the Split Is This Way ==

The diagnostic templates (dependency queries, related pages, all-templates nav) go on the '''template''' because that's the page someone is actually working on when a problem needs catching — this project has already caught two real bugs (a cycle-tracking flaw, a duplicate Cargo row) specifically because this information was visible in-place rather than requiring a context-switch to a separate doc page. The universal reference lists go on the '''doc''' because they're not diagnostic — they don't help catch anything specific to this page, they're just standing background material a reader consults once.

== Known Issue: `Template:` Namespace Limitations ==

Two confirmed, unresolved limitations specific to building on this pattern:

* '''No working transparency footer template exists for `Template:` namespace pages.''' `Standalone Transparency` and `Subpage Hub-Linked Transparency` are both confirmed broken here, root cause unidentified. See [[Known Site Issues & Fixes]]. Until a fix exists, `Template:` namespace pages using this pattern will have no transparency footer.
* '''Cargo may store duplicate rows for a page across multiple saves''' — confirmed on `Template:New Page Seed`. `limit=1` on the status query is a required display-level workaround, not a fix; the underlying duplicate should still be cleared via `Special:CargoTables` "Recreate data" when possible.

== Development Breadcrumb ==

This pattern has been tested on exactly one template/doc pair. It should be applied to at least one more before being treated as fully validated — watch specifically for whether the duplicate-row issue recurs, and whether a `Template:`-namespace-safe transparency solution changes this pattern once it exists.

{{RelatedPages}}
{{Standalone Transparency}}
{{Calibration Dependent}}
{{Calibration Dependencies Display}}
{{Calibration Maintenance}}
{{Framework Reference}}
{{Calibration Procedure Reference}} 

'''See the Game. Refuse the Game. Build Better.'''

[[Category:Meta & Framework]]
[[Category:Site Maintenance]]

<div style="display:none;">
{{Resource
| Title = Template/Doc Calibration Pattern
| URL = https://www.thesovereigngames.com/wiki/Template%2FDoc_Calibration_Pattern
| Description = The reference pattern for how a template and its /doc page should be structured and calibrated together as one unit.
| Category = Site Maintenance
}}
</div>

{{Admin Page Status
| categorization = Done
| calibration_review = Self-Assessment
| instrument_grade = Experimental
| validation = Low
| calibration_rationale = First formalization of a pattern developed and tested live on one real template/doc pair (New Page Seed). Genuinely working, but validated against only one instance — needs a second test case before being trusted as fully general. Documents two real, confirmed limitations (Template: namespace transparency, duplicate Cargo rows) rather than presenting the pattern as flawless.
| review_confidence = Moderate
| review_date = 2026-07-14
| reviewed_by = Sovereign
| priority = Core
| review_threshold = 30
| has_backlinks = Not checked
| outbound_links_valid = Not checked
| in_outline = No
| in_category_outline = No
| templates_complete = Done
| formatting_standard = Meets standard
| symmetry_check = Not applicable
| self_report_flagged = No
| terminology_consistent = Yes
| standing_check = Self-assessed only
| drift_report_status = Breadcrumb-Open
| depends_on = Template:New Page Seed; Template:New Page Seed/doc; Known Site Issues & Fixes; Calibration Failure Log
}}