PVERSE
DOCS

Conventions

Shared writing, structure, terminology, naming, and linking rules across PVERSE documentation.

Published: March 23, 2026
Updated: March 23, 2026
Section: DOCS
Purpose
This page is the SSOT for documentation conventions. If a rule concerns consistency of tone, structure, terms, links, or naming, it belongs here.

Overview

Conventions keep the PVERSE docs set readable, stable, and internally consistent. They exist so pages written across different lanes still feel like parts of one system rather than disconnected documents with conflicting voice, structure, or terminology.

This page does not define protocol guarantees, gameplay parameters, or infrastructure policy. It defines how documentation itself should be written and maintained: how pages should sound, how they should be structured, how names and routes should be formed, and how SSOT, glossaries, and changelogs relate to one another.

Scope

These conventions apply across the full PVERSE documentation system.

  • shared writing tone and voice across all lanes
  • terminology, capitalization, naming, and linking rules
  • page structure patterns and callout usage conventions
  • the relationship between docs, SSOT, glossaries, and changelog practice

Core Model

Documentation should privilege consistency over novelty. Readers should be able to predict how a page is organized, how a hard rule will be labeled, where to look for numeric truth, and what kind of statement they are reading. Conventions reduce ambiguity and make the docs set easier to maintain as it grows.

  • tone should remain neutral, technical, and boundary-aware
  • terms should map to one stable meaning across the docs
  • page structure should remain reader-first and predictable
  • numeric values belong in SSOT; docs explain meaning and boundaries

Operational Behavior

In practice, writers should treat this page as the grammar for the docs set. When drafting a new page, the writer should first check whether the page fits the standard structure, whether the key term already exists with a stable meaning, and whether any number being mentioned actually belongs in SSOT instead.

Under future growth, conventions should evolve carefully and forward-only. If a convention changes, it should be updated here and reflected in the docs changelog so readers and maintainers can understand when and why the writing model changed.

Constraints

  • conventions do not create new protocol guarantees or redefine lane boundaries
  • this page should not become a dumping ground for unrelated policy or implementation details
  • numeric parameters should not be duplicated here unless the page is explicitly documenting a snapshot
  • shared terms should not be overloaded with multiple meanings across different lanes

Integrity Considerations

Writing conventions are part of documentation integrity. Without them, readers start to treat similar pages differently, the same term begins to drift in meaning, and structural inconsistency makes the entire docs set harder to trust. Conventions preserve coherence across time and across lanes.

  • stable conventions reduce semantic drift across the docs
  • clear structure improves backward readability and maintenance
  • SSOT separation prevents narrative pages from becoming stale numeric copies

Writing tone and voice

  • Neutral and technical: describe systems and rules without marketing language.
  • Declarative over speculative: write what the system does and what constraints apply.
  • Short paragraphs: prefer clear lists and concise explanations over long narrative blocks.
  • Boundary-first: define what the page covers and what it does not cover.
Avoid
Hype, promises, or unverifiable claims. If something is not enforced by code or policy, describe it as a goal, not a guarantee.

Terminology rules

Capitalization

Proper system names are capitalized, such as Genesis, Founders, Season, Discovery, Mining, Refining, and Forging. Generic nouns remain lowercase unless they are part of a proper system name.

Singular meaning

Each term should map to one meaning across the docs. If a term becomes overloaded, introduce a new term instead of reusing the old one for a different concept.

  • Discovery defines what can appear; Mining defines what you get.
  • Changelog records changes over time; Snapshot is a point-in-time state summary.
  • SSOT defines numbers and constants; docs explain behavior; code enforces transitions.

Lane vs system

  • Lane — a documentation domain such as Token or Infrastructure.
  • System — a mechanism with defined inputs, outputs, and constraints.
  • Protocol boundary — the explicit rule that separates domains of responsibility.

Page structure conventions

Most pages should follow a stable, reader-first order:

  1. Purpose or Overview
  2. Core rule or main invariant
  3. Scope
  4. How it works or mechanics
  5. Constraints
  6. Examples where needed
  7. Summary
  8. Related pages
Rule
If a section defines a hard invariant, label it clearly and phrase it as a single sentence wherever possible.

Callout conventions

Use callouts only for high-signal content such as invariants, constraints, safety rules, and version notes.

  • Note — clarifying context or useful interpretation help
  • Warning — pitfalls, misunderstandings, or soft constraints
  • Danger — irreversible actions, security issues, or high-impact risks

Naming conventions

Routes

  • use kebab-case paths
  • use trailing slash canonical URLs
  • avoid version suffixes in routes; version belongs in metadata and changelogs
/docs/game-lane/core-loop/
/docs/token/liquidity-policy/
/docs/infrastructure/payment-engine/

Files

  • use index.html in each folder
  • one canonical page per route; avoid duplicates

Code and data conventions

Code blocks

  • prefer copyable blocks over screenshots
  • keep examples minimal and self-contained
  • use consistent naming in examples and do not mix placeholder styles

SSOT relationship

Numeric parameters and constants belong to SSOT. Docs describe behavior and intent. Code enforces transitions and records outcomes. 

SSOT defines numeric parameters.
Docs describe behavior.
Code enforces transitions.
Do not duplicate SSOT
Avoid copying numeric values into docs unless the page is explicitly a snapshot. Prefer linking to the relevant SSOT-backed source of truth.

Linking conventions

  • use canonical paths such as /docs/…/
  • link to the most specific page that answers the question
  • when a page depends on a boundary, link to /docs/protocol-boundaries/

Glossary relationship

Conventions define how terms are used. Glossaries define what terms mean within a lane. If a term is shared across multiple lanes, define it in Reference or the appropriate shared layer and link to it from lane glossaries.

Examples

Example: page structure

Purpose
Core rule
Scope
How it works
Constraints
Examples
Summary
Related pages

Example: tone

Bad:  PVERSE will revolutionize gaming.
Good: PVERSE defines a mining-economy gameplay system with enforced constraints.

Future Expansion

This page may expand over time as PVERSE adds more lanes, richer glossary cross-linking, more explicit docs templates, and stronger style guidance for changelog and snapshot pages. Even as the docs set grows, this page should remain the canonical rulebook for writing and organizing documentation consistently.

Summary

  • conventions keep the PVERSE docs set structurally and semantically consistent
  • tone should remain neutral, technical, and boundary-aware
  • terms should keep one stable meaning across lanes
  • docs define meaning, SSOT defines numbers, and code enforces transitions
Change process
If a convention changes, record it in the relevant docs changelog so readers and maintainers can track policy evolution over time.