OpenTracks/docs/README-STYLE.md

Repository README standard

Version: 1.0. Documentation language: English.

A README should explain the project, help a new reader start it, and point to detailed references. Keep project-specific instructions and existing attribution when applying this standard.

Original projects

Start with one # Project name heading and a short description of what the project does and who it serves. An optional local screenshot or banner may follow. Then add a navigation line linking to the level-two sections present in the document.

Use these level-two headings in this order. Omit sections that do not apply; do not add empty sections or filler just to match the template.

Section	Content
Features	Concrete capabilities and supported use cases.
Requirements	Runtime, hardware, services, and build prerequisites; distinguish build from runtime needs.
Getting started	Shortest complete path from checkout or download to a working result, including initial setup.
Configuration	Settings, defaults, required values, and example files. Explain prerequisites before commands that need them.
Usage	Common workflows, commands, and expected output or artifact locations.
Architecture	Project layout, interfaces, data model, or hardware overview.
Limitations	Known constraints and validation boundaries; keep critical setup constraints near the affected step too.
Development	Build, test, validation, and release instructions supported by repository files.
Documentation	Links to detailed guides, diagrams, screenshots, and this style guide.
Credits	Contributors, reused work, upstream sources, and existing AI-assistance disclosures.
License	Link to the actual project license; state explicitly when no project-level license file exists.

Keep specialized content under these headings using ### and ####. For example, put power variants under Configuration, pinouts under Architecture, and schematic downloads under Documentation or Architecture. Small component READMEs can use only the relevant sections and link back to the root README.

Forks

Use the same formatting rules, but introduce the fork before describing the original project. Start with one title, a short fork description, and clearly labeled links to upstream and the fork repository.

Use these headings in order, omitting optional sections when unnecessary:

1. Fork purpose
2. Changes from upstream
3. Requirements
4. Getting started
5. Configuration
6. Usage
7. Architecture
8. Limitations
9. Development
10. Upstream maintenance
11. Documentation
12. Credits
13. License

Explain why the fork exists, list its differences, and identify where to obtain its builds. Clearly label links to upstream builds, contribution channels, and screenshots. Include upstream synchronization instructions based on the actual workflow, and checks needed after merges.

Keep inherited documentation in README.upstream.md at the repository root. Keeping it beside the original README preserves relative links to assets. Retain upstream attribution, donations, and license notices there. Label any local corrections; this file is inherited documentation, not a claim to be the latest upstream version. After an upstream merge, refresh the inherited file and review the fork README separately. Do not overwrite the fork's explanation with the upstream README.

Borrowing a component or taking inspiration from another project does not by itself make the entire repository a fork. Explain that relationship under Credits and preserve component licensing.

Markdown and accuracy

• Write documentation in English. Preserve proper names and UI labels as shown in the product.
• Use one H1, sentence-case headings, and consecutive heading levels. Do not number headings.
• Separate paragraphs, headings, lists, tables, and fenced blocks with blank lines.
• Use - for unordered lists. Indent nested content consistently; use four spaces for nested unordered lists.
• Label fenced blocks: bash, sh, powershell, python, json, yaml, dotenv, text, or mermaid as appropriate.
• Run commands from the repository root unless a different working directory is explicitly stated.
• Use placeholders or portable example paths instead of private workstation paths. Never include real tokens, passwords, private keys, or local data.
• Link to versioned files using relative paths. Use full URLs for other repositories, services, and upstream sources. Avoid sibling-checkout links.
• Prefer Markdown. Use HTML only when it improves a gallery or layout; provide image alt text.
• Keep navigation anchors synchronized with headings. Avoid duplicate headings that create ambiguous anchors.
• Avoid decorative badges, repeated separators, promotional claims, and unsupported claims of production readiness or completed testing.
• Verify requirements and commands against manifests, scripts, configuration, and workflows. Distinguish previously documented results from checks performed during an edit.
• Preserve existing technical instructions, screenshots, credits, and license notices when reorganizing. Move long references into docs/ when useful and update links relative to their new location.
• Never infer a license from a badge, framework, dependency, or a different repository. License choices require an explicit project decision.

Maintenance

Update the README alongside changes to installation, configuration, commands, supported hardware, or release behavior. Check local links, navigation, and Markdown structure before committing. Run a command only when its effects are appropriate; a documentation check must not flash hardware, publish a release, send messages, or start an import.