Production-Ready Feature Documentation Checklist

Background

This list is intended to cover everything developers need to know to maintain a production-ready feature (or microservice). In an enterprise environment, documentation may sometimes just mean linking to existing policies rather than writing your own. Some things in the list may not apply to your feature or microservice at all!

Feature Documentation Checklist 📝

READMEs and Code Comments are Not Documentation
Many developers limit the documentation of their microservices to a README file in their repository or to comments scattered throughout the code. While having a README is essential, and all microservice code should contain appropriate comments, this is not production-ready documentation and requires that developers check out and search through the code.
- Production-Ready Microservices, page 119

• The feature or microservice has its own Documentation Page wherever your company keeps R&D Documentation (e.g. Confluence).
• A high-level description of the feature.
• Contact information
  • Paging Information to contact for Production Escalations 🚨
  • If applicable, contact info includes a link to your team's website or separate documentation page.
• An architecture diagram 🎨

This diagram should detail the architecture of the service, including its components, its endpoints, the request flow, its dependencies (both upstream and downstream), and information about any databases or caches... Architecture diagrams are essential for several reasons. It's nearly impossible to understand how and why a microservice works just by reading through the code, and so a well-designed architecture diagram is an easily understandable visual description and summary of the microservice.
- Production-Ready Microservices, page 121

• Information about the component's request flow(s), endpoints, dependencies, and stakeholders
  • Document all API endpoints of the service or feature.
  • Upstream Dependencies: which features or technologies does your component rely on? For each dependency, consider documenting:
    • Links to documentation for the upstream dependencies
    • Frequency of maintenance updates required due to these dependencies (e.g. if you are using something like Nodejs or Java, how often should you be checking for version updates?)
  • Downstream Stakeholders (e.g. specific features or other teams that rely on your feature)
• Decision Log
• On-call Runbook / Pager Playbook
  • Operations SOPs
  • Monitoring / Telemetry Dashboards
  • Alerts SOPs (step-by-step instructions that explain how to review logs and debug the issue that caused the alert)
• Developer's (or DevOps) Guide to the Feature
  • Links to relevant Developer Tools and Resources needed for the feature
  • Links to beginner's or quickstart guides to the tools and resources
• Automated Testing Suites - where to find them, how to run them, best practices, etc
• List of infrastructure resources that are deployed with the feature or microservice
• Step-by-step guide to setting up the feature for local development
  • Where is a good "entry point" for developers looking to read through the feature code? (e.g. file name, function name, etc)
  • How to set up local environment for development. Consider whether you need to document things like config files that are used, which authorization credentials are needed, etc
  • How to start the feature and step through the workflows of the feature. Include all commands or scripts that need to be run
  • How to verify that the feature is up and running correctly
• Links to documented Code Conventions, Style Guides used, or Lint Tool Configs
• Development Cycle and Deployment Pipeline
  • How do developers commit code to your feature? What are your expectations for pull requests?
  • How often is your code deployed to production? Do you follow a CI/CD model?
  • Do you use feature toggles to gate changes?
• Deep Dive on Technical Designs and Documentation. This is where you document your architecture design.

References

1. Production-Ready Microservices: Building Standardized Systems Across an Engineering Organization by Susan Fowler
2. Documenting Software Architectures: Views and Beyond by Judith Stafford, Robert Nord, Paulo Merson, Reed Little, James Ivers, David Garlan, Len Bass, Felix Bachmann, Paul Clements
3. Feature Toggles (aka Feature Flags) by Martin Fowler