README Guide

Clear documentation is essential for maintaining and scaling infrastructure code. Each type of repository (modules, projects, and workspace management) requires specific documentation approaches.

Module README Structure

1. Module Name and Version
   • Clear name following convention
   • Current version number
   • Supported Terraform versions
2. Description
   • Purpose of the module
   • Core functionality
   • Use cases
3. Features
   • Key capabilities
   • Optional features
   • Default behaviors
4. Usage
   • Basic example
   • Common configurations
   • Integration patterns
5. Requirements
   • Provider versions
   • Required permissions
   • Dependencies
6. Inputs
   • All variables
   • Type definitions
   • Default values
   • Required vs optional
7. Outputs
   • Available outputs
   • Type definitions
   • Usage examples
8. Resources Created
   • List of created resources
   • Resource naming patterns
   • Resource relationships

Project README Structure

1. Project Overview
   • Business purpose
   • Architecture diagram
   • Environment strategy
2. Dependencies
   • Required modules
   • Version requirements
   • External dependencies
3. Deployment
   • Branch strategy (dev/qa/main)
   • Deployment order
   • Required variables
4. Configuration
   • Environment differences
   • Variable management
   • Secret handling
5. Maintenance
   • Update process
   • Testing strategy
   • Troubleshooting

Workspace Management README Structure

1. Overview
   • Business unit scope
   • Environment strategy
   • Stack organization
2. Stack Configuration
   • Stack definitions
   • Branch mappings
   • Dependencies
3. Access Control
   • Team structure
   • Role definitions
   • Policy assignments
4. Variable Management
   • Environment variables
   • Secret management
   • Stack inheritance
5. Operational Procedures
   • Deployment process
   • Promotion workflow
   • Emergency procedures

Best Practices

1. Keep Updated
   • Update documentation with code changes
   • Version documentation with releases
   • Include changelog
2. Be Specific
   • Use concrete examples
   • Include error scenarios
   • Document known limitations
3. Include Context
   • Explain design decisions
   • Document trade-offs
   • Reference related components
4. Maintain Standards
   • Consistent formatting
   • Clear section hierarchy
   • Regular reviews

Remember: Good documentation reduces operational overhead and enables team scaling. Invest time in maintaining clear, accurate documentation.