Perastage

Documentation Policy

This document defines how Perastage documentation should be organized and maintained. The primary rule is that README.md stays short and acts as a landing page, while detailed workflows live in focused files under docs/.

README Scope

  • Keep README.md as an elevator pitch and quick-start entry point.
  • Limit it to project overview, highlights, minimal build/run steps, and links to deeper guides.
  • Do not move long troubleshooting logs, packaging checklists, or platform-specific edge cases into README.md.

Detailed Documentation Scope

Use dedicated documents for deeper topics:

  • docs/user/features.md for feature breakdowns and workflow summaries.
  • docs/developer/build.md for source builds, dependencies, toolchains and build troubleshooting.
  • docs/developer/packaging.md for installer and desktop integration behavior.
  • docs/user/ for operator workflows and reference documentation.
  • docs/user/troubleshooting.md for runtime problems with installed applications.
  • Existing policy/spec files (for example docs/developer/text_to_scene_rules.md and docs/developer/gdtf_mutation_policy.md) for behavior contracts.

User manual ownership

docs/user/ owns canonical English user-manual content; localized mirrors translate that content, and the website and packaged Help consume it. There is no independent in-app help prose source. See User Manual Pipeline for source paths, translation, runtime/package staging, and Console extraction contracts.

Public documentation HTML is generated from canonical Markdown by node tools/docs/build_static_docs.cjs and committed under docs/ for publishing. Never make editorial fixes in generated HTML: update Markdown and regenerate. Run node tools/docs/build_static_docs.cjs --check to reject stale artifacts. The hand-authored product landing page docs/index.html remains separate. Generated metadata and public identity belong to tools/docs/; descriptions come from canonical prose rather than a separate editorial inventory. The same build owns docs/sitemap.xml and docs/robots.txt, listing only the landing, Stable manifest pages and current indexable developer routes. --check rejects crawl artifact drift; release promotion commits the updated sitemap with Stable. Template changes apply to Next, developer pages and future promotions; existing Stable bytes and manifest hashes remain immutable between promotions.

docs/next/ follows main's canonical user Markdown. docs/stable/ is frozen from the latest published non-prerelease release tag and changes only through explicit promotion. Never edit generated Stable/Next HTML manually. Developer website documentation remains current-main content under docs/developer/; release-specific developer/source material is accessed through Git tags. Packaged offline Help corresponds to the exact application release.

Developer Documentation Authority

The Developer Documentation index is the canonical entry map. Canonical sources own project-wide policy; focused technical notes own only their named subsystem and link back rather than repeating parent policy.

Permanent documentation describes current behavior and contracts. Point-in-time audits, pull-request evidence, CI run logs, and checkpoint journals normally belong in Git and pull-request history. Retain historical material only when it has an explicit ongoing maintenance purpose that a current contract cannot serve. When staged work is complete, fold its durable rules into the current owner and remove chronological checkpoint prose.

Do not create a second exhaustive inventory. Keep volatile inventories, thresholds, and live measurements in their machine-enforced reports or policy files.

Formatting Rules

  • Use ## headings for major sections and ### for subtopics.
  • Keep paragraphs short and focused.
  • Prefer bullet lists and tables for structured information.
  • Use fenced code blocks for commands and snippets.
  • Write source, developer and reference documentation and code comments in English.
  • docs/user/locales/<locale>/ contains intentional translated user-manual mirrors; translate their operator-facing prose while preserving canonical technical and UI terms.

Localization Policy for Translated Manual Mirrors

When updating translated mirrors under docs/user/locales/<locale>/, keep UI terminology stable and searchable:

  • Do not translate exact UI labels for menus, panels, dialogs, tabs, and buttons.
  • Translate only explanatory narrative text around those labels.
  • Keep command names and option labels exactly as shown in the application UI.
  • Reuse the same canonical UI terms across all translated manual sections.

Minimum glossary of terms that must remain untranslated:

Keep in English Notes
Fixtures Tab/panel label.
Trusses Tab/panel label.
Hoists Tab/panel label.
Objects Tab/panel label.
Render style 3D Viewer context-menu entry.
Create from text Tools workflow entry.
Apply filter Create-from-text action button.
Create Create-from-text action button.
File, Edit, View, Tools Menu names.
Console, Layers, Layouts, Summary, Rigging, 2D Viewer, 3D Viewer, 2D Render Options, Layout View Panel/view names.

Cross-Linking Rules

  • Avoid duplicating large sections across files.
  • Link related guides using relative links.
  • When adding a new major workflow, add one short bullet to README.md Highlights and place details in the appropriate docs/*.md file.

Documentation Synchronization Checklist

Use this checklist in every PR that changes behavior, UX labels, or parsing contracts to keep user help and technical rules aligned.

1) User-facing functionality in the canonical manual

User-visible operator behavior must be updated in the appropriate canonical docs/user/*.md owner, including at least:

  • New or removed menu actions, dialogs, toolbar actions, or panel entries.
  • Changes to user-executed workflows (new steps, reordered steps, renamed actions, changed defaults).
  • New or changed keyboard/mouse shortcuts.
  • New or changed console commands, command syntax, or command scope/selection behavior.
  • Build-gated visibility changes that affect what users can access in Debug vs Release.
  • Any user-visible warning, limitation, or prerequisite needed to avoid incorrect usage.

Console command syntax/help changes must update the marked canonical section in docs/user/shortcuts-and-command-bar.md. Keep technical command parser contracts in Command API; cross-link rather than duplicate them.

2) Detailed rules that remain in docs/developer/text_to_scene_rules.md

Keep parser/scene-generation contracts in docs/developer/text_to_scene_rules.md as the technical source of truth, including:

  • Token grammar and normalization expectations (headers, separators, accepted aliases).
  • Parsing precedence and conflict resolution rules.
  • Placement/distribution algorithms, defaults, fallback behavior, and override hierarchy.
  • Coordinate/unit parsing semantics and value interpretation rules.
  • Error handling, skipped-line policy, and deterministic behavior requirements.

The canonical user manual should summarize only operator-facing behavior. Avoid duplicating the full parser contract there; link to docs/developer/text_to_scene_rules.md for details.

3) Criteria for updating both files in the same PR

Update both the appropriate docs/user/*.md owner and docs/developer/text_to_scene_rules.md in the same PR when any of the following is true:

  • A text-to-scene/rider parsing or scene-generation change is visible to users.
  • The same feature requires both a user workflow explanation and an update to parsing/placement technical rules.
  • UI labels/help examples must change to stay consistent with updated parser behavior.

If the change is purely internal and does not alter user-visible behavior, update only docs/developer/text_to_scene_rules.md when the technical contract changes.

PR self-check (required before merge)

  • I reviewed this checklist and updated the appropriate canonical docs/user/*.md owner where user-facing behavior changed.
  • I updated docs/developer/text_to_scene_rules.md where parser/scene-generation rules changed.
  • I updated both files in the same PR when both criteria applied.
  • I added cross-links instead of duplicating long rule sections.

Refactor-Only PR Checklist

Use this short checklist for PRs that claim no functional change:

  • No functional change confirmed (behavior, outputs, and user workflows unchanged).
  • One-line English comments added/maintained above touched function definitions.
  • CMake source lists updated explicitly when files are split or moved (no implicit source discovery).
  • If text-to-scene parsing or scene-generation behavior changed, docs/developer/text_to_scene_rules.md was updated in the same PR.
  • If GUI shortcut mappings/scope/precedence changed, docs/developer/gui_shortcut_architecture.md was updated in the same PR.
  • Hotspot growth was avoided by extracting responsibilities when touching near-limit files.

Assets and Media

  • Store screenshots and diagrams under docs/ or resources/ as appropriate.
  • Embed media only where it adds clear instructional value.
  • Compress images before committing to keep repository size manageable.

License Reference

  • Keep LICENSE.txt as the canonical, unmodified GNU GPL version 3 legal text.
  • State the project licensing choice consistently as GPL-3.0-or-later in project-facing metadata, and use “GNU General Public License version 3 or later” in prose.
  • Reference LICENSE.txt from README.md and any documentation that needs the full legal text.
Back to top