computer-playbook/docs/contributing/documentation.md

Documentation 📝

All project documentation MUST be reachable at docs.infinito.nexus.

Comments 💬

• You SHOULD write code so it is logical and self-explanatory and usually does not need comments.
• You MUST add code comments only when an exception, edge case, or surprising decision would otherwise confuse readers.
• You MUST use comments to explain why something is unusual, not to restate what obvious code already does.
• When keeping an intentionally retained outdated version pin, you MUST document the exception at the pin site with a local TODO comment in the file's normal comment style (#todo, # TODO, or similar) and explain why it remains pinned so the root cause stays visible until it can be fixed.

Requirement Keywords (RFC 2119) 📋

You MUST use RFC 2119 keywords in all documentation to express requirement levels unambiguously:

Keyword	Meaning
MUST / REQUIRED / SHALL	Absolute requirement — no deviation allowed.
MUST NOT / SHALL NOT	Absolute prohibition — never do this.
SHOULD / RECOMMENDED	Strongly recommended — deviation requires justification.
SHOULD NOT / NOT RECOMMENDED	Strongly discouraged — allowed only with justification.
MAY / OPTIONAL	Permitted but not required.

Links 🔗

• You MUST NOT use the full URL as link text. Use the domain name, here, or the filename instead — never the full path.
• After See, you MUST use the domain name as link text, not here. here is only acceptable when the surrounding sentence reads naturally with it (e.g. "More information here").
• For communication links such as Matrix, email, or phone, you MUST show only the value itself as link text, without any protocol prefix or URL wrapper.

Type	MUST NOT	MUST
Web link	https://docs.infinito.nexus/setup	docs.infinito.nexus, here, a descriptive label, or setup.md
File link	docs/contributing/flow/workflow.md	workflow.md or Contribution Flow
Email	mailto:hello@infinito.nexus	hello@infinito.nexus
Matrix	https://matrix.to/#/@user:infinito.nexus	@user:infinito.nexus
Phone	tel:+491234567890	+49 123 456 7890

Semantics and Writing ✍️

• You MUST keep code and comments in English.
• You MUST fix nearby wording and semantic issues when you touch a file, and correct obvious nearby issues proactively in the same pass.
• You SHOULD use emojis when they make the text more visually appealing, improve the mood, and increase readability.

Headlines 🏷️

• You SHOULD place emojis after the headline text to visually highlight headings and improve scannability.
• You MUST NOT place emojis before the headline text, as this interferes with heading hierarchy rendering in some tools.
• You MUST NOT add emojis to headlines in docs/agents/ files, as these are machine-readable instruction files where emojis interfere with parsing.

Documentation Structure 🗂️

Role README

Every Ansible role MUST contain a README.md. See readme_base.md for the required structure, section order, and formatting rules.

Markdown

• You SHOULD prefer README.md for directory-level documentation when a human-facing entry point already exists.
• You MUST NOT place README.md files under docs/. Documentation files MUST be cross-linked to each other directly instead. All content under docs/ is automatically indexed via the root index.rst toctree glob (docs/**) — per-directory index files are usually not needed.
• You MUST keep core information inside the repository, either in code or in .md files.
• You MUST use .md files for commands, workflows, setup, and contributor guidance.
• You MUST NOT use .md files to describe implementation logic that is already visible in the code.

Sphinx

• The root index.rst uses a :glob: toctree (docs/**) to automatically include every documentation page.
• Sphinx indexing SHOULD happen automatically through that root :glob: toctree.
• You SHOULD avoid creating or maintaining manual per-directory indexes when automatic indexing already covers the same pages. An additional index.rst inside a docs/ subdirectory is NOT RECOMMENDED because the root index already covers those pages automatically, but it MAY be added when a focused local entry point materially improves navigation. If such a local index.rst is added, it SHOULD stay minimal and MUST NOT duplicate a manually curated page inventory that the automatic index already provides. You MUST NOT add a README.md inside any docs/ subdirectory.
• You MUST keep cross-links between .md files up to date so readers can navigate between related pages.