computer-playbook/docs/contributing/code/role/readme_base.md

Role README

Every Ansible role MUST contain a README.md at the role root. This page defines the required structure and content rules.

Structure

Role README files MUST follow this section order. Optional sections MAY be omitted when they add no value for the role.

1. Title (required)

The H1 heading MUST be the human-readable name of the application or service, not the role ID.

# Nextcloud

2. Description (required)

A short paragraph that describes what the software is — not what the role does. Link the software name to its official website on first use.

## Description

[Nextcloud](https://nextcloud.com/) is a self-hosted file sync and share platform …

3. Overview (required)

A short paragraph that describes what the role does — what it deploys, configures, and integrates. Reference any companion documentation files (e.g. Administration.md) here using file-name link text.

## Overview

This role deploys Nextcloud using Docker Compose …
For administration details see [Administration.md](./Administration.md).

4. Features (required)

A bulleted list of the most important capabilities. Each item MUST start with a bold label followed by a colon and a short explanation.

## Features

- **Self-hosted:** Run the application under your own domain …
- **LDAP Integration:** Authenticate users via a central directory …

5. Purpose (optional)

Use this section when the motivation for the role is not obvious from Description and Overview. Omit it for roles where the purpose is self-evident.

6. Developer Notes (optional)

Link to role-local documentation files such as Administration.md, Installation.md, or Development.md. Use file-name link text, never the full path.

## Developer Notes

See [Administration.md](./Administration.md) for live container inspection and LDAP configuration.

7. Further Resources (optional)

A list of external links relevant to the software or the deployment. Link text MUST be a descriptive label or the domain name — never the full URL.

## Further Resources

- [Nextcloud Official Website](https://nextcloud.com/)
- [Nextcloud Admin Manual](https://docs.nextcloud.com/…)

8. Credits (required)

Always the last section. MUST follow this fixed format:

## Credits

Developed and maintained by **Kevin Veen-Birkenbach**.
Learn more at [veen.world](https://www.veen.world).
Part of the [Infinito.Nexus Project](https://s.infinito.nexus/code).
Licensed under the [Infinito.Nexus Community License (Non-Commercial)](https://s.infinito.nexus/license).

Formatting Rules

• Role README files MUST NOT use emojis in headings. Emojis in role READMEs interfere with automated tooling that parses heading text.
• Body text MAY use emojis where they improve readability.
• All headings MUST use sentence-case (capitalize only the first word and proper nouns).
• Link text MUST follow the rules in documentation.md.