zhongwei/gh-basher83-lunar-claude-plugins-infrastructure-ansible-best-practices

Fork 0

Files

Zhongwei Li 4768fb755a Initial commit

2025-11-29 18:00:24 +08:00

31 KiB

Raw Blame History

Documentation Templates

Summary: Pattern Confidence

Analyzed 7 geerlingguy roles: security, users, docker, postgresql, nginx, pip, git

Universal Patterns (All 7 roles):

Consistent README structure: Title + Badge → Description → Requirements → Variables → Dependencies → Example → License → Author (7/7 roles)
CI badge showing test status with link to workflow (7/7 roles)
Code-formatted variable defaults with detailed descriptions (7/7 roles)
Example playbook section with working examples (7/7 roles)
Inline code formatting for variables, file paths, commands (7/7 roles)
Explicit "None" for empty sections (Requirements, Dependencies) (7/7 roles)
License + Author sections with links (7/7 roles)
Variable grouping for related configuration (7/7 roles)
Commented list examples showing optional items (7/7 roles)

Contextual Patterns (Varies by complexity):

Warning/caveat sections: security-critical roles have prominent warnings, simple roles don't need them
Variable documentation depth: complex roles (postgresql) have extensive inline docs, simple roles (pip) are more concise
Example complexity: simple roles show basic examples, complex roles show multiple scenarios
Troubleshooting sections: recommended for roles that modify critical services (SSH, networking), optional for simple roles
Complex variable documentation: roles with 5+ optional dict attributes show ALL keys with inline comments

Evolving Patterns (Newer roles improved):

PostgreSQL shows best practices for complex variable documentation: show all keys, mark required vs optional, document defaults
nginx demonstrates template extensibility documentation (Jinja2 block inheritance)
Complex roles provide comprehensive inline examples in defaults/ files as primary documentation

Sources:

geerlingguy.security (analyzed 2025-10-23)
geerlingguy.github-users (analyzed 2025-10-23)
geerlingguy.docker (analyzed 2025-10-23)
geerlingguy.postgresql (analyzed 2025-10-23)
geerlingguy.nginx (analyzed 2025-10-23)
geerlingguy.pip (analyzed 2025-10-23)
geerlingguy.git (analyzed 2025-10-23)

Repositories:

Pattern Confidence Levels (Historical)

Analyzed 2 geerlingguy roles: security, github-users

Universal Patterns (Both roles use identical approach):

✅ README structure - Both follow: Title + Badge → Description → Requirements → Variables → Dependencies → Example → License → Author
✅ CI badge - Both include GitHub Actions CI badge with link to workflow
✅ Variable documentation format - Code-formatted default + detailed description
✅ Example playbook section - Both show minimal working example with vars
✅ Inline code formatting - Backticks for variables, file paths, commands
✅ Commented list examples - Show example list items as comments
✅ "None" for empty sections - Explicit "None" instead of omitting (Requirements, Dependencies)
✅ License + Author sections - Both include MIT license and author with links
✅ Variable grouping - Related variables documented together with shared context

Contextual Patterns (Varies by role complexity):

⚠️ Warning/caveat section - security has prominent security warning, github-users doesn't need one
⚠️ Variable detail level - security has extensive variable docs with warnings, github-users is more concise (fewer variables)
⚠️ Example complexity - security shows vars_files pattern, github-users shows inline vars (simpler)
⚠️ Troubleshooting section - Neither role has explicit troubleshooting (could be added)

Key Finding: README documentation follows a strict template across roles. Only the caveat/warning section varies based on role risk profile.

Overview

This document captures documentation patterns from production-grade Ansible roles, demonstrating how to create clear, comprehensive README files that help users understand and use the role effectively.

README Structure

Pattern: Comprehensive README Template

Description: A well-structured README that follows a consistent format, providing all necessary information for users to understand and use the role.

File Path: README.md

Standard README Sections:

Title and badges
Caveat/Warning (if applicable)
Role description
Requirements
Role Variables
Dependencies
Example Playbook
License
Author Information

Section 1: Title and Badges

Example Code:

# Ansible Role: Security (Basics)

[![CI](https://github.com/geerlingguy/ansible-role-security/actions/workflows/ci.yml/badge.svg)](https://github.com/geerlingguy/ansible-role-security/actions/workflows/ci.yml)

Key Elements:

Clear title - Role name with descriptive subtitle
CI badge - Shows test status (builds confidence)
Badge links to CI - Users can see test results

When to Use:

Always include clear role title
Add CI badge if you have automated testing
Link badges to their status pages
Consider adding Galaxy badge, version badge, downloads badge

Badge Examples:

[![CI](https://github.com/user/repo/workflows/ci.yml/badge.svg)](https://github.com/user/repo/actions)
[![Ansible Galaxy](https://img.shields.io/badge/galaxy-user.rolename-blue.svg)](https://galaxy.ansible.com/user/rolename)
[![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE)

Anti-pattern:

Don't skip the title (obvious but happens)
Avoid outdated or broken badges
Don't add badges that don't provide value

Section 2: Caveat/Warning (Optional)

Example Code:

**First, a major, MAJOR caveat**: the security of your servers is YOUR
responsibility. If you think simply including this role and adding a firewall
makes a server secure, then you're mistaken. Read up on Linux, network, and
application security, and know that no matter how much you know, you can
always make every part of your stack more secure.

That being said, this role performs some basic security configuration on
RedHat and Debian-based linux systems. It attempts to:

  - Install software to monitor bad SSH access (fail2ban)
  - Configure SSH to be more secure (disabling root login, requiring
    key-based authentication, and allowing a custom SSH port to be set)
  - Set up automatic updates (if configured to do so)

There are a few other things you may or may not want to do (which are not
included in this role) to make sure your servers are more secure, like:

  - Use logwatch or a centralized logging server to analyze and monitor
    log files
  - Securely configure user accounts and SSH keys (this role assumes you're
    not using password authentication or logging in as root)
  - Have a well-configured firewall (check out the `geerlingguy.firewall`
    role on Ansible Galaxy for a flexible example)

Again: Your servers' security is *your* responsibility.

Key Elements:

Prominent warning - Sets expectations clearly
Scope definition - What the role does and doesn't do
Additional recommendations - Points to complementary practices
Emphasis - Bold, italics, repetition for important points

When to Use:

Security-related roles (critical warnings)
Roles that could cause service disruption
Roles with common misunderstandings
Complex roles with limited scope

Anti-pattern:

Don't add warnings for routine roles
Avoid legal disclaimers (that's what LICENSE is for)
Don't be condescending

Section 3: Requirements

Example Code:

## Requirements

For obvious reasons, `sudo` must be installed if you want to manage the
sudoers file with this role.

On RedHat/CentOS systems, make sure you have the EPEL repository installed
(you can include the `geerlingguy.repo-epel` role to get it installed).

No special requirements for Debian/Ubuntu systems.

Key Elements:

System requirements - Software that must be pre-installed
OS-specific requirements - Different requirements per platform
How to meet requirements - Links to other roles or instructions
Explicit "no requirements" statement - Clarity when none exist

When to Use:

List any software that must be installed first
Document repository requirements (EPEL, PPAs)
Mention privilege requirements (become/sudo)
Note Python library dependencies
State "None" if no requirements (clear communication)

Anti-pattern:

Don't assume users know about EPEL or special repos
Avoid listing Ansible itself (assumed)
Don't skip this section (at least say "None")

Section 4: Role Variables

Example Code:

## Role Variables

Available variables are listed below, along with default values (see
`defaults/main.yml`):

    security_ssh_port: 22

The port through which you'd like SSH to be accessible. The default is port
22, but if you're operating a server on the open internet, and have no
firewall blocking access to port 22, you'll quickly find that thousands of
login attempts per day are not uncommon. You can change the port to a
nonstandard port (e.g. 2849) if you want to avoid these thousands of
automated penetration attempts.

    security_ssh_password_authentication: "no"
    security_ssh_permit_root_login: "no"
    security_ssh_usedns: "no"
    security_ssh_permit_empty_password: "no"
    security_ssh_challenge_response_auth: "no"
    security_ssh_gss_api_authentication: "no"
    security_ssh_x11_forwarding: "no"

Security settings for SSH authentication. It's best to leave these set to
`"no"`, but there are times (especially during initial server configuration
or when you don't have key-based authentication in place) when one or all
may be safely set to `'yes'`. **NOTE: It is _very_ important that you quote
the 'yes' or 'no' values. Failure to do so may lock you out of your server.**

    security_ssh_allowed_users: []
    # - alice
    # - bob
    # - charlie

A list of users allowed to connect to the host over SSH.  If no user is
defined in the list, the task will be skipped.

    security_sudoers_passwordless: []
    security_sudoers_passworded: []

A list of users who should be added to the sudoers file so they can run any
command as root (via `sudo`) either without a password or requiring a
password for each command, respectively.

    security_autoupdate_enabled: true

Whether to install/enable `yum-cron` (RedHat-based systems) or
`unattended-upgrades` (Debian-based systems). System restarts will not
happen automatically in any case, and automatic upgrades are no excuse for
sloppy patch and package management, but automatic updates can be helpful
as yet another security measure.

    security_fail2ban_enabled: true

Whether to install/enable `fail2ban`. You might not want to use fail2ban if
you're already using some other service for login and intrusion detection
(e.g. [ConfigServer](http://configserver.com/cp/csf.html)).

Documentation Pattern:

For each variable:

Show default value - Code-formatted with actual default
Description - What it does, when to use it
Context - Why you might change it
Examples - Show different values for lists/dicts
Warnings - Important notes (quoting, locking out, etc.)

Formatting Guidelines:

Use 4-space indentation for default values
Group related variables together
Add blank lines between variable groups
Use inline code formatting for values
Bold important warnings
Comment out example list items

When to Use:

Document ALL variables from defaults/main.yml
Group related variables (ssh_, autoupdate_, etc.)
Provide context, not just description
Include warnings for dangerous settings
Show example values for complex structures

Anti-pattern:

Don't just list variables without explanation
Avoid documenting vars/ (internal implementation)
Don't skip context (users need to know WHY)
Avoid stale documentation (keep in sync with defaults/)

Pattern: Variable Table Format (Alternative)

Description: Some roles use a table format for variable documentation. While geerlingguy.security doesn't use this, it's a valid alternative pattern.

Example Table Format:

## Role Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `security_ssh_port` | `22` | SSH port number |
| `security_ssh_password_authentication` | `"no"` | Enable password authentication |
| `security_fail2ban_enabled` | `true` | Install and configure fail2ban |

When to Use:

Roles with many simple variables
When brief descriptions are sufficient
For quick reference guides

Comparison:

Format	Best For	Pros	Cons
Text with examples	Complex variables, detailed context	Detailed explanations, examples	More verbose
Table	Simple variables, quick reference	Concise, scannable	Limited detail space

Virgo-Core Preference:

Use text format with examples (matches geerlingguy pattern) for main documentation, optionally add table for quick reference.

Section 5: Dependencies

Example Code:

## Dependencies

None.

When Dependencies Exist:

## Dependencies

This role depends on:

- `geerlingguy.repo-epel` (for RedHat/CentOS systems)
- `geerlingguy.firewall` (recommended but optional)

The role will automatically install required dependencies from Ansible Galaxy.

Key Elements:

Explicit "None" - Clear when no dependencies
List dependencies - With context about why needed
Distinguish required vs optional - Important for users
Note automatic installation - Reduces confusion

When to Use:

Always include this section
List role dependencies from meta/main.yml
Note recommended complementary roles
State "None" if no dependencies

Anti-pattern:

Don't skip this section
Avoid listing collection dependencies here (put in Requirements)

Section 6: Example Playbook

Example Code:

## Example Playbook

    - hosts: servers
      vars_files:
        - vars/main.yml
      roles:
        - geerlingguy.security

*Inside `vars/main.yml`*:

    security_sudoers_passworded:
      - johndoe
      - deployacct

Key Elements:

Minimal working example - Shows basic usage
Variable override example - Demonstrates customization
Multiple files - Shows playbook and vars file
Real-world example - Not generic foo/bar examples
Indentation - 4 spaces for YAML, maintains readability

Enhanced Example Pattern:

## Example Playbook

### Basic Usage

    - hosts: all
      roles:
        - geerlingguy.security

### Custom Configuration

    - hosts: webservers
      vars:
        security_ssh_port: 2222
        security_fail2ban_enabled: true
        security_autoupdate_enabled: true
      roles:
        - geerlingguy.security

### Advanced Example with Sudoers

    - hosts: appservers
      vars:
        security_sudoers_passwordless:
          - deploy
        security_sudoers_passworded:
          - developer
          - operator
      roles:
        - geerlingguy.security

When to Use:

Always include at least one example
Show basic usage first
Add advanced examples for complex features
Use realistic variable values
Include multiple scenarios if role has distinct use cases

Anti-pattern:

Don't use only generic examples (foo, bar, example.com)
Avoid incomplete examples (missing required vars)
Don't show every possible variable (overwhelming)

Section 7: License and Author

Example Code:

## License

MIT (Expat) / BSD

## Author Information

This role was created in 2014 by [Jeff Geerling](https://www.jeffgeerling.com/),
author of [Ansible for DevOps](https://www.ansiblefordevops.com/).

Key Elements:

License name - Clear license statement
Author information - Who created/maintains it
Links - Author website, book, company
Year created - Provides context

When to Use:

Always include license (required for Galaxy)
Add author name and contact
Link to LICENSE file for full text
Keep it brief

Anti-pattern:

Don't include full license text in README (use LICENSE file)
Avoid complex author information

Additional Documentation Patterns

Pattern: Troubleshooting Section

Description: While geerlingguy.security doesn't include a troubleshooting section, more complex roles should include one.

Example Troubleshooting Section:

## Troubleshooting

### SSH Connection Refused After Running Role

If you lose SSH connectivity after running this role, you may have:

1. Changed the SSH port without updating your firewall rules
2. Disabled password authentication without setting up SSH keys
3. Set `security_ssh_allowed_users` without including your username

**Solution:** Access the server via console and check `/etc/ssh/sshd_config`.

### Fail2ban Not Starting

If fail2ban fails to start, check that the log files it monitors exist:

    ls -la /var/log/auth.log

On some minimal systems, these log files may not exist until a service
writes to them.

**Solution:** Create empty log files or disable fail2ban temporarily.

When to Use:

Roles that modify critical services (SSH, networking)
Roles with common configuration mistakes
Roles with tricky OS-specific issues
Complex roles with multiple failure modes

Anti-pattern:

Don't include troubleshooting for roles that are straightforward
Avoid listing every possible error (focus on common issues)

Pattern: Inline Code and Formatting

Formatting Patterns from README:

Inline code - Use backticks: fail2ban, sudo, /etc/ssh/sshd_config
File paths - Always use inline code: defaults/main.yml
Commands - Inline code for short commands: sudo systemctl restart ssh
Variable names - Inline code: security_ssh_port
Code blocks - Use 4-space indentation for YAML/code examples
Emphasis - Bold for important warnings, italics for emphasis
Lists - Use - for unordered, numbers for ordered

Example:

To configure SSH port, set `security_ssh_port` in your playbook variables.
The configuration is written to `/etc/ssh/sshd_config` and validated with
`sshd -T -f %s` before applying. **WARNING**: Changing the SSH port without
updating firewall rules will lock you out.

Comparison to Virgo-Core Roles

system_user Role

README Analysis:

Matches:

✅ Has clear title
✅ Good role description
✅ Documents variables
✅ Includes example playbook
✅ Has license and author sections

Gaps:

❌ No CI badge (no CI yet)
⚠️ Variable documentation less detailed (could add more context)
⚠️ Could add troubleshooting section (SSH key issues common)
⚠️ No table of contents (nice-to-have for longer docs)

Priority Actions:

Important: Enhance variable documentation with usage context (30 min)
Important: Add troubleshooting section (1 hour)
Nice-to-have: Add CI badge after implementing CI (5 min)

proxmox_access Role

README Analysis:

Matches:

✅ Comprehensive variable documentation
✅ Good examples
✅ Security warnings included

Gaps:

❌ No CI badge
⚠️ Could add more example playbooks (different scenarios)
⚠️ Troubleshooting section would help (token creation failures)

Priority Actions:

Important: Add troubleshooting for common token issues (1 hour)
Important: Add more example scenarios (30 min)
Nice-to-have: Add requirements section (15 min)

proxmox_network Role

README Analysis:

Matches:

✅ Good structure
✅ Clear variable documentation
✅ Network architecture context

Gaps:

❌ No CI badge
⚠️ Network troubleshooting section would be valuable
⚠️ Could add verification examples (how to check it worked)

Priority Actions:

Important: Add network troubleshooting section (1 hour)
Important: Add verification examples (30 min)
Nice-to-have: Add network topology diagram (1 hour)

Template: Complete README Structure

# Ansible Role: [Role Name]

[![CI](badge-url)](ci-url)
[![Ansible Galaxy](badge-url)](galaxy-url)

[Brief role description - what it does, key features]

[Optional: Warning/caveat section for critical roles]

## Requirements

[List prerequisites, or "None"]

## Role Variables

Available variables are listed below, along with default values (see
`defaults/main.yml`):

    variable_name: default_value

[Description of variable, when to change it, usage examples]

    another_variable: []
    # - example1
    # - example2

[Description with examples]

## Dependencies

[List role dependencies, or "None"]

## Example Playbook

### Basic Usage

    - hosts: all
      roles:
        - rolename

### Custom Configuration

    - hosts: servers
      vars:
        variable_name: custom_value
      roles:
        - rolename

## Troubleshooting

[Optional: Common issues and solutions]

## License

MIT / BSD / Apache 2.0

## Author Information

This role was created by [Author Name](link), [additional context].

Validation: geerlingguy.postgresql

Analysis Date: 2025-10-23 Repository: https://github.com/geerlingguy/ansible-role-postgresql

README Structure

Pattern: Comprehensive README template - ✅ Confirmed
- PostgreSQL follows same structure: Title + Badge → Description → Requirements → Variables → Dependencies → Example → License → Author
- 4/4 roles follow identical README structure

Variable Documentation

Pattern: Code-formatted default + detailed description - ✅ EXCELLENT EXAMPLE
- PostgreSQL has extensive variable docs (50+ variables documented)
- Each variable group includes:
  - Code block with default value
  - Detailed description of purpose
  - Usage context and examples
  - Inline comments for complex structures
- Example quality:
```
    postgresql_databases:
      - name: exampledb # required; the rest are optional
        lc_collate: # defaults to 'en_US.UTF-8'
        lc_ctype: # defaults to 'en_US.UTF-8'
        encoding: # defaults to 'UTF-8'
```
- Validates: Complex dict variables need inline comment documentation
- 4/4 roles use this documentation pattern

CI Badge

Pattern: GitHub Actions CI badge - ✅ Confirmed
- PostgreSQL includes CI badge with link to workflow
- 4/4 roles have CI badges

Example Playbook

Pattern: Basic + vars_files example - ✅ Confirmed
- Shows minimal playbook + vars file pattern
- Includes example variable values for databases and users
- 4/4 roles provide working examples

Requirements Section

Pattern: Explicit requirements or "None" - ✅ Confirmed
- PostgreSQL states: "No special requirements"
- Mentions become: yes requirement
- 4/4 roles include Requirements section (even if "None")

Dependencies Section

Pattern: Explicit "None" - ✅ Confirmed
- PostgreSQL states: "None."
- 4/4 roles include Dependencies section

Advanced Pattern: Complex Variable Tables

Pattern Evolution: PostgreSQL uses structured tables for complex options:
- hba_entries: Lists all available keys with descriptions
- databases: Shows optional attributes with defaults
- users: Documents every possible parameter
- Insight: When variables have 5+ optional attributes, use structured documentation
- Recommendation: For complex dict structures, show all keys even if optional

Documentation for Complex Structures

Pattern: Show all keys, even optional - ✅ NEW INSIGHT
- PostgreSQL documents every possible key for postgresql_databases, postgresql_users, postgresql_privs
- Includes comments like "# required" vs "# optional"
- Shows default values inline: # defaults to 'en_US.UTF-8'
- Best practice: Comprehensive documentation prevents user confusion

Key Validation Findings

What PostgreSQL Role Confirms:

✅ README structure is universal (4/4 roles identical)
✅ Variable documentation format is universal (4/4 roles)
✅ CI badges are universal (4/4 roles)
✅ Example playbooks are universal (4/4 roles)
✅ Explicit "None" for empty sections is universal (4/4 roles)
✅ Inline code formatting is universal (4/4 roles)

What PostgreSQL Role Demonstrates:

🔄 Complex variables need extensive inline documentation
🔄 Show ALL available keys for dict structures, even optional ones
🔄 Use comments to indicate required vs optional vs defaults
🔄 Large variable sets (20+) benefit from grouping in documentation

Pattern Confidence After PostgreSQL Validation (4/4 roles):

README structure: UNIVERSAL (4/4 roles identical)
Variable documentation: UNIVERSAL (4/4 use same format)
CI badges: UNIVERSAL (4/4 roles have them)
Example playbooks: UNIVERSAL (4/4 provide examples)
Explicit "None": UNIVERSAL (4/4 use it)
Complex variable docs: VALIDATED (postgresql shows best practices for complexity)

Validation: geerlingguy.pip

Analysis Date: 2025-10-23 Repository: https://github.com/geerlingguy/ansible-role-pip

README Structure

Pattern: Standard sections - ✅ Confirmed
- Title with CI badge
- Description: "Installs Pip (Python package manager) on Linux"
- Requirements section (mentions EPEL for RHEL/CentOS)
- Role Variables section with defaults and descriptions
- Dependencies section (None.)
- Example Playbook section
- License and Author Information
- 6/6 roles follow identical README structure

Variable Documentation

Pattern: Simple variable table - ✅ Confirmed
- pip_package: Default python3-pip, shows alternative for Python 2
- pip_executable: Documents auto-detection, shows override example
- pip_install_packages: Shows list format with dict options
- All 3 variables documented with defaults and usage context
Pattern: List-of-dicts inline example - ✅ Confirmed
- pip_install_packages shows dict keys: name, version, state, extra_args, virtualenv
- Example shows installing specific version: docker==7.1.0
- Shows AWS CLI installation example
- 6/6 roles document list variables with inline examples

Requirements Section

Pattern: Explicit prerequisites - ✅ Confirmed
- States: "On RedHat/CentOS, you may need to have EPEL installed"
- Recommends geerlingguy.repo-epel role
- Key insight: Even simple roles document prerequisites

Example Playbook

Pattern: Single basic example - ✅ Confirmed
- Shows installing 2 packages (docker, awscli)
- Demonstrates vars: section with pip_install_packages
- Clean, minimal example for utility role
- Validates: Simple roles don't need complex examples

Key Validation Findings

What pip Role Confirms:

✅ README structure universal even for minimal roles (6/6 roles)
✅ All variables documented even when only 3 total (6/6 roles)
✅ CI badge present even for simple roles (6/6 roles)
✅ Example playbooks scaled appropriately (simple role = simple example)
✅ Prerequisites documented even when minimal

Pattern Confidence After pip Validation (6/6 roles):

README structure: UNIVERSAL (6/6 roles identical)
Variable documentation: UNIVERSAL (6/6 document all variables)
CI badges: UNIVERSAL (6/6 roles have them)
Example playbooks: UNIVERSAL (6/6, scaled to complexity)

Validation: geerlingguy.git

Analysis Date: 2025-10-23 Repository: https://github.com/geerlingguy/ansible-role-git

README Structure

Pattern: Standard sections - ✅ Confirmed
- Title with CI badge
- Description: "Installs Git, a distributed version control system"
- Requirements section (None.)
- Role Variables section with comprehensive variable list
- Dependencies section (None.)
- Example Playbook section
- License and Author Information
- 7/7 roles follow identical README structure

Variable Documentation

Pattern: Grouped variables - ✅ Confirmed
- git_packages: Package list with platform-specific defaults
- git_install_from_source: Boolean flag with clear purpose
- Source install variables grouped together (workspace, version, path, force_update)
- Key insight: Utility roles with options group related variables
Pattern: Boolean flags clearly explained - ✅ Confirmed
- git_install_from_source: "false by default. If set to true, installs from source"
- git_install_force_update: Explains version downgrade protection
- 7/7 roles document boolean flag purpose and default

Requirements Section

Pattern: Explicit "None" - ✅ Confirmed
- States: "None."
- 7/7 roles include Requirements section even if none needed

Example Playbook

Pattern: Multiple scenarios - ✅ Confirmed
- Shows package installation example
- Implies source installation available via variables
- Validates: Utility roles with multiple modes show key scenarios

Key Validation Findings

What git Role Confirms:

✅ README structure universal across all role types (7/7 roles)
✅ Variable grouping for related options (7/7 roles)
✅ Boolean flags clearly explained (7/7 roles)
✅ CI badge standard even for simple roles (7/7 roles)
✅ Documentation scales with role complexity

Pattern Confidence After git Validation (7/7 roles):

README structure: UNIVERSAL (7/7 roles identical)
Variable documentation: UNIVERSAL (7/7 document all variables with context)
CI badges: UNIVERSAL (7/7 roles have them)
Example playbooks: UNIVERSAL (7/7 provide working examples)
Explicit "None": UNIVERSAL (7/7 use for empty sections)
Variable grouping: UNIVERSAL (7/7 group related variables)
Boolean flag documentation: UNIVERSAL (7/7 explain purpose clearly)

Summary

Universal Patterns Identified:

Consistent README structure (title → requirements → variables → examples → license)
CI badges for test status
Comprehensive variable documentation with defaults and context
Multiple example playbooks (basic → advanced)
Explicit "None" statements for empty sections
Inline code formatting for variables, files, commands
Bold warnings for critical information
Commented examples for list variables
Show ALL keys for complex dict structures, even optional ones

Key Takeaways:

Variable documentation should include defaults AND context
Examples should progress from simple to complex
Warnings prevent common mistakes
Consistent formatting improves readability
Explicit "None" is better than omitting sections
Troubleshooting saves support time
Complex variables need inline documentation showing all available keys

Next Steps:

Enhance Virgo-Core role READMEs with:

More detailed variable context
Troubleshooting sections
CI badges (after implementing testing)
Additional example scenarios
For complex variables, show all available keys with inline comments

31 KiB Raw Blame History

Documentation Templates

Summary: Pattern Confidence

Pattern Confidence Levels (Historical)

Overview

README Structure

Pattern: Comprehensive README Template

Section 1: Title and Badges

Section 2: Caveat/Warning (Optional)

Section 3: Requirements

Section 4: Role Variables

Pattern: Variable Table Format (Alternative)

Section 5: Dependencies

Section 6: Example Playbook

Section 7: License and Author

Additional Documentation Patterns

Pattern: Troubleshooting Section

Pattern: Inline Code and Formatting

Comparison to Virgo-Core Roles

system_user Role

proxmox_access Role

proxmox_network Role

Template: Complete README Structure

Validation: geerlingguy.postgresql

README Structure

Variable Documentation

CI Badge

Example Playbook

Requirements Section

Dependencies Section

Advanced Pattern: Complex Variable Tables

Documentation for Complex Structures

Key Validation Findings

Validation: geerlingguy.pip

README Structure

Variable Documentation

Requirements Section

Example Playbook

Key Validation Findings

Validation: geerlingguy.git

README Structure

Variable Documentation

Requirements Section

Example Playbook

Key Validation Findings

Summary

31 KiB

Raw Blame History