Repository Documentation Standards

Goal: Establish consistent documentation standards for all code repositories using standardized templates for README, OVERVIEW, BUILD, and RUNBOOK files.

Resources:

• README Template
• OVERVIEW Template
• BUILD Template
• RUNBOOK Template

Steps

1. Accomplish the goal Identify Required Documentation
2. Accomplish the goal Implement Documentation Templates
3. Accomplish the goal Customize Template Content
4. Accomplish the goal Commit and Review Documentation
5. Done!

Identify Required Documentation

1. Determine which documentation templates are needed for your repository based on its purpose:

   - README.md: Required for all repositories
   - OVERVIEW.md: Required for service/product repositories 
   - BUILD.md: Required for repositories that need build instructions
   - RUNBOOK.md: Required for services with operational procedures

2. For each template, identify the key information that needs to be included based on the repository's purpose and audience.
3. Done!

Implement Documentation Templates

1. Download or copy the appropriate templates from the /devops/repo-documentation/templates/ directory:

   - README-template.md: Basic repository information and navigation
   - OVERVIEW-template.md: System architecture and design decisions
   - BUILD-template.md: Build and test instructions
   - RUNBOOK-template.md: Operational procedures and troubleshooting

2. Place template files in your repository's root directory, renaming them to remove the "-template" suffix.
3. Done!

Customize Template Content

1. For the README.md file:

   - Update the project name and description
   - List key features and capabilities 
   - Add specific getting started instructions
   - Update links to other documentation files
   - Add repository-specific contribution guidelines

2. For the OVERVIEW.md file (if applicable):

   - Define the system purpose and scope
   - Document the architecture with diagrams
   - List and describe all major components
   - Document data flow and external dependencies
   - Explain key design decisions and trade-offs

3. For the BUILD.md file (if applicable):

   - Document all prerequisites and environment setup
   - Provide step-by-step build instructions
   - Include test execution commands
   - Document deployment procedures
   - Add troubleshooting for common build issues

4. For the RUNBOOK.md file (if applicable):

   - Document key service metrics and normal ranges
   - Create alerts with severity levels and remediation steps
   - Document common operational procedures
   - Include disaster recovery processes
   - Add appropriate contact information

5. Done!

Commit and Review Documentation

1. Review all documentation files to ensure they are complete and accurate.
2. Commit the documentation files with your code using a descriptive commit message.
3. Create a pull request that includes the documentation files.
4. Request review from appropriate team members who can verify the documentation accuracy.
5. Address any feedback or suggestions from the review process.
6. Done!