Documentation standard

Rules for every page in this repository. bun run docs:lint enforces the parts marked lint; the rest is reviewed by hand. The standard was adopted through plan 20260913-2344-documentation-standard; changes to it go through the PMA workflow.

1. Areas and kinds

Every page belongs to exactly one area and declares exactly one kind in frontmatter.

Area	Directory	Language	Kinds allowed
Governance	bizplan/governance/	zh, .en.md variants	governance, guide
Product packages	bizplan/product/<line>/	zh	spec, design, guide, brief, evaluation, foundation (in shared/)
Research	bizplan/research/{market,industry,engineering}/	zh	report, proposal, review
Vendor catalogues	bizplan/research/vendors/{pdm,gateway,switch,keypad}/	zh	catalog; report for the landscape page
Evidence archives	bizplan/research/{data,sources}/	n/a	CSV, PDF, scripts, manifest.csv, SHA256SUMS
Project records	docs/	en	PMA task, plan, decision, changelog, architecture, this standard, templates
Unpublished references	refs/	n/a	third-party manuals kept out of the site

Kind	Definition
governance	A controlled planning document whose figures other documents cite: business plan, product plan, market and commercial models, compliance matrix, assumptions register, open questions.
spec	A product Level 1 target specification. The only kind that may set Level 1 values.
design	A product Level 2 document: design appendix, data model, integration spec, application architecture, commissioning package, reference board. Must not change Level 1 values.
guide	An external-facing delivery document for suppliers and contract manufacturers: requirements restated, acceptance, quotation scope. Also the internal PPT build guide.
brief	An external-facing product description for customers, installers, dealers, and sales. Restates capability; never a requirement source.
evaluation	A non-binding comparison or device evaluation. Never a decision record; a spec cites it only in its open-items chapter.
foundation	A cross-product technical baseline: the YBO CAN protocol, the configuration schema.
report	A research report on market, industry, certification, or technology.
proposal	An engineering proposal awaiting adoption. Does not revise controlled specifications until adopted through the workflow.
review	An assessment of an external or historical document.
catalog	One supplier record with the six fixed sections: company, product family, procurement and price, openness, relation to YBO, sources.
index	A directory entry page.

2. Frontmatter

Every page under bizplan/ carries YAML frontmatter with scalar values only. Pages under docs/task/ and docs/plan/ keep the PMA format and are exempt; other docs/ pages carry title only.

---
title: YBO Core —— 目标规格        # equals the H1; breadcrumb label on index pages
kind: spec                          # part 1
status: draft                       # draft | active | superseded | archived
updated: 2026-09-13                 # last content change, YYYY-MM-DD
version: R0.3                       # governance, spec, design, guide, foundation
product: P01                        # product kinds only
level: 1                            # spec = 1, design = 2
lifecycle: spec-draft               # spec only: concept | spec-draft | evt | dvt | pvt | released
evidenceDate: 2026-09-08            # catalog and report
supersededBy: ../engineering/x.md   # required when status is superseded
decision: ../../../docs/decisions/x.md   # spec only: the decision that waives a package slot
---

• lint title and kind are required; kind: index only on index.md.
• lint status, updated required on every non-index page; updated is an ISO date, not in the future.
• lint version required on governance, spec, design, guide, foundation.
• lint lifecycle allowed only on spec; supersededBy required with, and only with, status: superseded, and must resolve.
• lint product kinds under bizplan/product/ carry product.
• status is document maturity: draft (being written or not adopted), active (current and citable), superseded (replaced; first paragraph names the successor), archived (kept for record; not linked from indexes).
• lifecycle is product maturity, set once on the Level 1 spec. Level 2 pages do not repeat it.
• version: governance v1.x; product R0.x while draft, R1.0 when frozen for a gate. Bump only when a numbered value or requirement changes; typo fixes bump updated only.
• The theme renders these fields above the H1 (DocMeta.vue). Status, version, and date lines are not written in prose.

3. Filenames

• lint ASCII lower-case kebab-case, .md; English words even when the content is Chinese; .en.md for language variants.
• lint Product packages: P<nn>-<product>[-<slot>[-<aspect>]].md (part 4). The upper-case ID token is the one exception to lower-case. Shared foundations: X<nn>-<slug>.md.
• lint Research: <slug>.md inside a topic directory; no numeric prefix. Ordering belongs to the index table.
• Vendor catalogues: <vendor-slug>.md, filed once under the primary category; other categories cross-reference it.
• Evidence: data/<topic>/<table>.csv, sources/<topic>/<document>.pdf with manifest.csv and SHA256SUMS per topic.
• Project records: PMA formats. Legacy IDs are never renamed; they are closed or completed in place.

4. Product packages

One package per product ID. A product line with several products holds line-level files plus one sub-package per product. Every package has the same slots.

Slot	File	Kind	Audience	Required
Entry	index.md	index	everyone	always
Specification	P<nn>-<product>.md	spec	internal engineering, governance	always
Design	P<nn>-<product>-design.md, or -design-<aspect>.md when split	design	internal engineering, contract design	from spec-draft
Supplier guide	P<nn>-<product>-guide.md	guide	suppliers, contract manufacturers	before evt when outsourced
Product brief	P<nn>-<product>-brief.md	brief	customers, installers, dealers, sales	always; a draft stub is acceptable at concept
Evaluations	evaluations/<slug>.md	evaluation	internal engineering	optional

• lint Nothing else lives in a package. A page that fits no slot is an evaluation, a research report (research/), or a decision (docs/decisions/).
• lint One spec per package; a brief always; a design once lifecycle passes concept; slot files carry the spec's product slug. A product line directory (one that holds sub-packages) needs only its line spec and brief. A spec whose frontmatter decision resolves to a record in docs/decisions/ is exempt from the design slot.
• evaluations/ has no index of its own; its pages are listed in the owning package's index.md with the evaluations/ prefix.
• The entry page states positioning, tier, lifecycle, and the slot table with each file's status. It is the only inventory of the package.
• The spec is the only requirement source. The design must not change Level 1 values. The guide restates requirements for a supplier and adds acceptance and quotation scope. The brief restates capability for a buyer and adds nothing.
• Adding a product: copy docs/templates/product-package/, rename the placeholders, add the row in PRODUCT-PLAN and bizplan/product/index.md.
• A package that deliberately departs from the slot set (for example a single self-contained spec) records the deviation and a sunset date in docs/decisions/.

5. Page layout

• H1 equals frontmatter title.
• Directly after the H1, a relations list with fixed labels in fixed order, only the lines that apply: 产品入口, 治理摘要, Level-1 规格, 设计附录, 总交付要求, 引用的基础文件, 依据, 适用产品, 取代说明. Labels use a full-width colon.
• A superseded page opens its first paragraph with the successor link.
• Chapter templates: 16 numbered chapters for hardware specs, 11 for software and concept products, six fixed sections for catalogues, the skeletons in docs/templates/ for the other kinds.
• Every controlled page (governance, spec, design, guide, foundation) ends with ## 变更记录 as a table 日期 | 版本 | 变更 | 记录; the last column links the task or changelog entry.
• Chinese pages use full-width punctuation; numbers, units, and identifiers stay half-width with a space between a CJK character and a Latin token.

6. Index pages

• lint Every page-bearing directory has an index.md with title, kind: index, one scope paragraph, and a document table.
• lint Each page is listed once in its own directory index; archived pages are not listed; listed files exist.
• lint A directory whose pages differ in kind or status uses the columns 文档 | 类型 | 状态 | 内容 and the labels below; a uniform directory (one kind, one status, such as a vendor category) may state kind and status once in the intro and use domain-specific columns.
• Parent indexes link to child directories, not to grandchildren.

Kind	类型	Status	状态
governance	治理	draft	草案
spec	规格	active	现行
design	设计	superseded	已取代
guide	指南	archived	归档
brief	说明
evaluation	评估
foundation	基础
report	报告
proposal	提案
review	评审
catalog	目录

7. Cross-references

• Relative Markdown links only, resolved from the containing file. No bare filenames in backticks as references.
• Governing figures cite PRODUCT-PLAN by section (§P1, §6).
• A design cites its spec in the relations list; a spec cites its governance section; a proposal cites the spec it would change and states that it does not change it.
• A superseded page is linked only from its successor and from the index's historical table.
• Retired task and plan IDs link to their changelog entry.
• A renamed or moved page gets a line in .vitepress/public/_redirects from the old clean URL to the new one.

8. Quality gate

bun run docs:lint && bun run docs:build && git diff --check

docs:lint runs the checks marked lint above. docs:build fails on dead links. git diff --check catches whitespace errors. The deploy workflow runs all three.

9. Decisions

A deliberate deviation from this standard or from a skill rule is recorded as docs/decisions/<YYYY-MM-DD>-<slug>.md using docs/templates/decision.md, with context, decision, consequences, and a sunset date at which it is reviewed. docs/decisions/index.md lists them.