Documentation uses short imperative sentences for steps (Run the following command) and the present tense to describe (This function returns…). Avoid simply and just: what is simple for you may not be for the reader.
Easy phrases (94)
Please refer to the README for setup instructions.
When to use it: Directing someone to the project README file
This function returns a list of active users.
When to use it: Writing an inline comment describing a function's return value
See the changelog for a list of recent updates.
When to use it: Pointing someone to the changelog file
Make sure to update the docs before merging.
When to use it: Reminding a teammate to keep documentation in sync with code changes
This endpoint accepts a JSON body with the following fields.
When to use it: Documenting an API endpoint's request format
Add a brief description of your changes to the pull request.
When to use it: Asking someone to document their PR properly
I'll add code comments to explain the business logic.
When to use it: Committing to document complex business rules in the code
The API returns a 404 status code if the resource is not found.
When to use it: Documenting an API error response in the docs
Before running the project locally, make sure you have Node.js 18 or later installed.
When to use it: Writing prerequisites in an onboarding or setup guide
The configuration file supports hot reloading, so changes take effect without restarting the application.
When to use it: Documenting hot reload capabilities in configuration docs
We need to update the README with the new setup instructions.
When to use it: When the project setup process has changed and the README is outdated
Please add a code comment explaining why we chose this approach.
When to use it: During code review when a non-obvious implementation decision lacks explanation
I wrote an onboarding guide so new developers can get started quickly.
When to use it: When a team member creates documentation to help new hires ramp up
Don't forget to update the changelog before we tag the release.
When to use it: Reminding a team member to document changes before cutting a new release
Let's add architecture diagrams to the documentation so new developers can understand the system at a glance.
When to use it: Proposing visual documentation to improve system understanding
The environment setup instructions need to be tested on a clean machine.
When to use it: When verifying that setup documentation works for someone starting from scratch
Our internal wiki has become outdated and needs a comprehensive review.
When to use it: When recognizing that internal documentation has fallen behind the actual system state
Every pull request that changes the API must include documentation updates.
When to use it: Establishing a team policy about keeping docs in sync with code changes
Comments should explain why the code does something, not what it does.
When to use it: Giving feedback during code review about the quality of code comments
I added inline documentation for all public methods in the SDK.
When to use it: Reporting completion of documentation work on a public-facing library
Please keep the README concise and link to detailed docs for advanced configuration.
When to use it: Advising on README structure to avoid overwhelming new users
Avoid using TODO comments as a substitute for proper task tracking.
When to use it: Advising against overreliance on code comments for project management
Add a table of contents to the README since it has grown to over fifty sections.
When to use it: When a README has become too long to navigate without an index
Stale documentation is worse than no documentation because it misleads developers.
When to use it: Arguing for the importance of keeping documentation up to date
Write the error codes table so support engineers can quickly identify issues.
When to use it: Creating reference documentation that maps error codes to their meanings
The how-to guide should include common pitfalls and their solutions.
When to use it: Improving a how-to guide with troubleshooting information
I wrote a step-by-step tutorial on how to integrate our webhook system.
When to use it: Creating educational content for a developer platform
Add a prerequisites section to the setup guide listing required software versions.
When to use it: Improving setup documentation with dependency information
The wiki page on our caching strategy has not been updated since last year.
When to use it: Identifying stale internal documentation that needs attention
Every public function must have a documentation comment describing its parameters and return value.
When to use it: Enforcing documentation standards in a code review checklist
Let's add a glossary to the docs defining all domain-specific terms we use.
When to use it: Proposing to add terminology definitions to make documentation more accessible
Please update the environment variable documentation to include the new feature flag.
When to use it: When a new feature flag has been added but the configuration docs are not updated
Good documentation is an investment that pays off by reducing support tickets and onboarding time.
When to use it: Advocating for documentation investment during a team planning meeting
We added a frequently asked questions page based on the most common support requests.
When to use it: Using support data to drive documentation improvements
We decided to use Markdown for all documentation because it renders well on GitHub and is easy to diff.
When to use it: Explaining the rationale behind the documentation format choice
New team members should complete the documentation scavenger hunt during their first week.
When to use it: Describing an onboarding exercise that familiarizes new hires with existing documentation
I moved the legacy setup instructions to an archive page so they do not confuse new users.
When to use it: Cleaning up documentation by separating outdated content from current content
Remove the outdated screenshots from the docs and replace them with current ones.
When to use it: Updating visual documentation to match the current state of the application
I noticed the README still references the old package name that we renamed three months ago.
When to use it: Finding outdated information in documentation during a routine check
We maintain separate getting-started guides for mobile developers and backend developers.
When to use it: Describing audience-specific documentation for different developer personas
The README badge shows the build status, code coverage, and the latest release version.
When to use it: Describing visual status indicators commonly placed in project README files
The technical writing team reviews all public-facing documentation before it goes live.
When to use it: Describing the quality assurance process for documentation publishing
The README should include setup instructions for new developers
When to use it: Onboarding documentation
The changelog needs to be updated before the release
When to use it: Release documentation process
This function is missing its documentation comment
When to use it: Adding inline code documentation
The glossary helps new team members understand our terminology
When to use it: Creating a project glossary
Can you review the inline comments for accuracy?
When to use it: Reviewing code comments
The user guide needs screenshots of the latest interface
When to use it: Updating visual documentation
I added a prerequisites section at the top of the guide
When to use it: Setting up documentation structure
The contributing guide outlines how to submit pull requests
When to use it: Open source contribution documentation
Let's create a FAQ section based on the most asked questions
When to use it: Building FAQ documentation
The style guide ensures consistency across the documentation
When to use it: Documentation standards
The release notes should highlight new features and bug fixes
When to use it: Writing release documentation
The parameter description is missing from the function header
When to use it: Completing function documentation
The onboarding documentation should include common pitfalls
When to use it: Helping new team members avoid mistakes
The README badges show the build status and test coverage
When to use it: Adding status badges to documentation
Let's document the environment variables required to run the app
When to use it: Configuration documentation
Let's add a table of contents to make the document easier to navigate
When to use it: Improving documentation navigation
Please update the installation instructions for the latest version
When to use it: Keeping setup docs current
We should add cross-references between related documentation pages
When to use it: Linking documentation together
The code review checklist should be part of the documentation
When to use it: Standardizing review processes
Let's keep the documentation language simple and avoid jargon
When to use it: Writing accessible documentation
Let's add a known issues section to the release notes
When to use it: Documenting known limitations
Can you proofread the documentation for grammar and spelling?
When to use it: Documentation quality review
I added a section on how to run the project locally
When to use it: Local development documentation
Can you add a comparison table between the free and premium features?
When to use it: Feature comparison documentation
Let's create a cheat sheet with the most common commands
When to use it: Quick reference documentation
The coding standards document should be the first thing new developers read
When to use it: Establishing coding conventions
Let's add a section about the development workflow and branching strategy
When to use it: Git workflow documentation
Let's create a video walkthrough for the complex setup process
When to use it: Creating video documentation
The documentation template standardizes how we write new guides
When to use it: Documentation templates
Can you add sequence numbers to the API workflow steps?
When to use it: Ordering documentation steps
The documentation should specify which platforms are supported
When to use it: Platform compatibility docs
Can you write a brief summary at the top of each documentation page?
When to use it: Documentation readability improvement
The documentation review is part of our definition of done
When to use it: Documentation as quality gate
I added a troubleshooting flowchart to help diagnose common problems
When to use it: Visual troubleshooting guides
The documentation should explain the difference between each log level
When to use it: Logging documentation
Let's create a visual guide for the entire user journey
When to use it: User experience documentation
The documentation should link to the related Jira tickets for context
When to use it: Connecting docs to project management
Can you add a section explaining the conventions used throughout the docs?
When to use it: Documentation meta-information
The API documentation clearly distinguishes between required and optional fields
When to use it: API field documentation
The API documentation should include curl examples for quick testing
When to use it: Adding practical API examples
The documentation portal should have a feedback mechanism for readers
When to use it: Documentation feedback loop
The documentation should include a system requirements section
When to use it: System prerequisites documentation
We should add a decision tree for choosing the right component
When to use it: Component selection guide
The documentation should include a section on how to report security issues
When to use it: Security reporting documentation
The documentation portal has a dark mode toggle for better readability
When to use it: Documentation UX improvement
Let's add a list of all the environment variables with their descriptions
When to use it: Environment variable reference
The documentation uses consistent terminology throughout all sections
When to use it: Documentation consistency
Let's create a glossary of abbreviations used in the codebase
When to use it: Abbreviation reference documentation
The documentation includes a compatibility matrix for browser and OS support
When to use it: Compatibility documentation
The API documentation should group endpoints by resource type
When to use it: API documentation organization
I created a reference card summarizing the most important configuration values
When to use it: Quick reference documentation
Can you add timestamps to the documentation pages to show when they were last updated?
When to use it: Documentation freshness tracking
Intermediate phrases (125)
We should document the environment variables required to run the project.
When to use it: Suggesting adding configuration documentation
Each parameter is described in the table below with its type and default value.
When to use it: Introducing a parameters table in API documentation
This section covers the migration steps from version 2 to version 3.
When to use it: Writing a migration guide introduction
Deprecated: This method will be removed in the next major release. Use fetchData() instead.
When to use it: Writing a deprecation notice in code documentation
The architecture follows a clean separation between the data layer, domain layer, and presentation layer.
When to use it: Describing the app architecture in a design document
Please include a code example showing how to initialize the SDK.
When to use it: Requesting a usage example in documentation
Known issue: The search feature may return duplicate results under heavy load.
When to use it: Documenting a known bug in release notes or troubleshooting guide
Authentication is handled via JWT tokens passed in the Authorization header.
When to use it: Explaining the authentication mechanism in API docs
The troubleshooting section addresses the most commonly reported issues and their solutions.
When to use it: Introducing the troubleshooting section of a guide
To configure the database connection, set the DATABASE_URL environment variable in your .env file.
When to use it: Explaining database configuration in setup documentation
The API docs are missing examples for the authentication endpoints.
When to use it: When reviewing API documentation and finding incomplete sections
This function is complex enough to warrant a detailed docstring.
When to use it: During code review when a complex function lacks proper documentation
We should document the database schema changes in the migration guide.
When to use it: When planning a database migration and needing to communicate changes to the team
Can you write a troubleshooting guide for the most common deployment errors?
When to use it: Asking a team member to create operational documentation for known issues
The FAQ section should cover questions about rate limiting and pagination.
When to use it: When building out an API documentation site and planning the FAQ content
The migration guide should include step-by-step instructions and a rollback plan in case something goes wrong.
When to use it: Discussing requirements for a version migration guide
We need to document the API rate limits so consumers know how many requests they can make per minute.
When to use it: Adding rate limit information to API documentation
Our contributing guidelines explain how to set up the development environment and submit pull requests.
When to use it: Describing the content of an open source project's CONTRIBUTING.md file
We need to add a deprecation notice with the recommended alternative approach.
When to use it: When sunsetting a feature and needing to guide users to the replacement
The tutorial walks through building a REST API from scratch with authentication.
When to use it: Describing the scope of a how-to guide in developer documentation
Each release note should highlight breaking changes at the top of the document.
When to use it: Setting standards for how release notes should be structured
We use JSDoc annotations to generate our TypeScript library documentation.
When to use it: Explaining the documentation tooling used in a JavaScript/TypeScript project
I created a quick-start guide that gets developers to their first API call in five minutes.
When to use it: Describing a new developer experience improvement in API documentation
The upgrade path from the legacy system is documented in the migration playbook.
When to use it: Directing team members to existing documentation about a system migration
We generate our API reference documentation directly from the source code annotations.
When to use it: Explaining the documentation generation pipeline to a new team member
The Swagger UI lets developers test API endpoints interactively from the documentation.
When to use it: Explaining the benefits of interactive API documentation
The configuration file supports twelve parameters, and each one is documented with valid ranges.
When to use it: Describing thorough configuration documentation with validation details
I set up a documentation linter to catch broken links and formatting issues automatically.
When to use it: Implementing automated quality checks for documentation
We need to version our API documentation separately from the codebase.
When to use it: Discussing documentation versioning strategy for a public API
Each microservice has its own README explaining its purpose, dependencies, and how to run it locally.
When to use it: Describing documentation standards in a microservices architecture
The release notes follow the keep-a-changelog format with added, changed, fixed, and removed sections.
When to use it: Describing the structure used for organizing release notes
Include curl examples alongside the SDK code samples in the API reference.
When to use it: Improving API documentation accessibility for developers who prefer raw HTTP calls
The changelog entry should be written from the user's perspective, not the developer's.
When to use it: Giving feedback on how to write user-friendly changelog entries
The troubleshooting guide needs a decision tree to help narrow down the root cause.
When to use it: Improving a troubleshooting document with a structured diagnostic approach
The internal knowledge base should have a dedicated section for incident response procedures.
When to use it: Organizing operational documentation within a company knowledge management system
We track documentation coverage the same way we track code coverage.
When to use it: Describing a mature documentation practice with metrics and accountability
The API rate limit headers should be explained in the authentication section of our docs.
When to use it: Identifying where rate limit information should be documented in the API reference
The runbook should specify the exact commands to run, not just describe the general procedure.
When to use it: Reviewing a runbook and requesting more actionable content
The database documentation should include a section on backup and recovery procedures.
When to use it: Ensuring database documentation covers operational aspects beyond just the schema
We should write a code style guide that documents our team's conventions for naming and formatting.
When to use it: Proposing documentation of coding standards for team consistency
Make sure to cross-reference related documentation pages so readers can find additional context.
When to use it: Improving documentation navigation through internal linking
The configuration reference lists every option with its type, default value, and a brief description.
When to use it: Describing a well-structured configuration documentation page
We automated the deployment of our documentation site using a continuous integration pipeline.
When to use it: Describing the documentation deployment infrastructure
The onboarding checklist includes reading the architecture overview, setting up the local environment, and running the test suite.
When to use it: Outlining the key steps in a developer onboarding process
Avoid writing documentation that duplicates what the code already communicates through good naming.
When to use it: Discussing when documentation adds value versus when it becomes redundant noise
The troubleshooting page should be organized by symptom so users can find answers based on what they observe.
When to use it: Structuring troubleshooting documentation for better usability
The deprecation timeline gives users twelve months to migrate before the old API is shut down.
When to use it: Communicating a deprecation schedule in API documentation
The wiki should be searchable and every page should have an owner responsible for keeping it current.
When to use it: Establishing governance practices for internal documentation
Can you add a code example to this API reference?
When to use it: Enhancing API documentation
We should document the error codes and their meanings
When to use it: Creating error reference documentation
Please add the return type description to the docstring
When to use it: Completing function documentation
I wrote a troubleshooting section for the most common issues
When to use it: Creating self-service support docs
The API endpoint documentation is outdated and needs a refresh
When to use it: Updating stale documentation
Let's add a sequence diagram to explain this workflow
When to use it: Using visual diagrams in documentation
The configuration options should be documented with default values
When to use it: Documenting configurable settings
We need to add deprecation notices to the old API methods
When to use it: Marking deprecated functionality
The documentation should be versioned alongside the code
When to use it: Documentation versioning strategy
We should add type annotations to improve the documentation clarity
When to use it: Using type information for documentation
This technical specification needs peer review before publishing
When to use it: Documentation review process
I documented the data model relationships in a diagram
When to use it: Creating data model documentation
Can you write a quick start guide for the SDK?
When to use it: Creating getting started documentation
Let's use Swagger to generate the API documentation automatically
When to use it: Automated documentation tools
I noticed the code samples in the docs don't compile anymore
When to use it: Maintaining documentation accuracy
We should add a data dictionary for the database tables
When to use it: Database documentation
The API rate limits should be clearly documented for consumers
When to use it: Documenting API constraints
I created a decision log to track our architectural choices
When to use it: Recording project decisions
The class diagram needs to be updated after the refactoring
When to use it: Keeping diagrams in sync with code
Can you add usage examples for each public method?
When to use it: Creating comprehensive method documentation
I wrote a tutorial that walks through building a feature from scratch
When to use it: Creating tutorial documentation
The testing strategy document outlines our quality assurance approach
When to use it: QA documentation
I added examples showing both success and error response formats
When to use it: Documenting API response formats
The webhook documentation needs to include payload examples
When to use it: Documenting webhook integrations
We documented the design system with component specifications
When to use it: Design system documentation
The dependency list should include version requirements and licenses
When to use it: Documenting project dependencies
The documentation should include accessibility guidelines for the UI
When to use it: Accessibility documentation
We need to update the architecture overview after adding the new service
When to use it: Maintaining system architecture docs
The API changelog tracks all breaking and non-breaking changes
When to use it: API change management documentation
The integration guide explains how to connect with third-party services
When to use it: Third-party integration documentation
Let's document the feature flags and how they affect behavior
When to use it: Feature flag documentation
The data flow documentation shows how information moves through the system
When to use it: System data flow documentation
The API documentation should include request and response headers
When to use it: Complete API documentation
I documented the localization workflow for adding new languages
When to use it: Internationalization process documentation
We need inline documentation for the complex business logic
When to use it: Documenting domain-specific code
Can you update the entity relationship diagram with the new tables?
When to use it: Maintaining database diagrams
The documentation search needs to be indexed for better discoverability
When to use it: Improving documentation search
We should keep a log of all the technical debt we identify
When to use it: Technical debt tracking docs
The API sandbox documentation helps developers test without affecting production
When to use it: Sandbox environment docs
The auto-generated documentation needs manual review for accuracy
When to use it: Validating auto-generated docs
The API pagination documentation should show cursor-based and offset examples
When to use it: Pagination documentation
Let's add interactive code samples that readers can run directly
When to use it: Interactive documentation
I documented the design tokens used across the component library
When to use it: Design token documentation
We need to document the data validation rules for each input field
When to use it: Input validation documentation
The documentation needs to be accessible to non-technical stakeholders
When to use it: Writing for mixed audiences
I updated the API documentation to reflect the new response format
When to use it: Keeping API docs in sync
We should document how the cron jobs are scheduled and monitored
When to use it: Scheduled jobs documentation
The component storybook serves as living documentation for the UI
When to use it: UI component documentation
Can you document the environment-specific configuration differences?
When to use it: Environment configuration docs
The documentation should clearly state the supported authentication methods
When to use it: Authentication documentation
We need to keep the API mock server responses in sync with the documentation
When to use it: Mock server documentation consistency
The documentation build system checks for broken links automatically
When to use it: Documentation CI/CD
I documented the notification system with all trigger conditions
When to use it: Notification system documentation
Can you document the differences between the development and production builds?
When to use it: Build configuration documentation
Let's consolidate the scattered documentation into a single source of truth
When to use it: Documentation centralization
The permission matrix shows which roles can access each feature
When to use it: Access control documentation
We need a clear diagram of the state transitions in this workflow
When to use it: State machine documentation
The documentation versioning follows semantic versioning alongside the codebase
When to use it: Version-aligned documentation
The documentation should include performance optimization tips for developers
When to use it: Performance best practices docs
Let's document the feature toggle naming conventions for consistency
When to use it: Feature flag naming documentation
The analytics event documentation maps each event to its business purpose
When to use it: Analytics tracking documentation
We should document the CI pipeline stages and what each one validates
When to use it: CI/CD pipeline documentation
Let's document the error codes with actionable resolution steps
When to use it: Error resolution documentation
The API documentation includes rate limit headers in the response examples
When to use it: Rate limit documentation details
I documented the test data generation process and seed scripts
When to use it: Test data documentation
Let's document the edge cases that the validation layer handles
When to use it: Validation logic documentation
The documentation should explain how the feature flag evaluation works
When to use it: Feature flag evaluation documentation
Can you create a mapping between the old and new API endpoints?
When to use it: API migration mapping documentation
I added annotations to the architecture diagram explaining each layer
When to use it: Annotated architecture diagrams
The SDK documentation includes getting started guides for each platform
When to use it: Multi-platform SDK docs
The documentation should warn about known limitations of the current implementation
When to use it: Limitation documentation
I documented the health check endpoints and their expected responses
When to use it: Health check endpoint documentation
The documentation should specify the maximum payload size for each endpoint
When to use it: API constraints documentation
Let's add a section on how the feature was designed and why
When to use it: Design rationale documentation
The documentation maps each microservice to its owning team
When to use it: Service ownership documentation
The documentation should include a dedicated section for mobile-specific behavior
When to use it: Platform-specific documentation
The documentation explains how to set up local development with Docker
When to use it: Docker setup documentation
Advanced phrases (81)
Breaking change: The response format for the /users endpoint has been updated to include pagination metadata.
When to use it: Writing a breaking change entry in the changelog
The module exports a singleton instance that should be initialized once during application startup.
When to use it: Documenting initialization requirements for a module
Rate limiting is enforced at 100 requests per minute per API key. Exceeding this limit returns a 429 status code.
When to use it: Documenting rate limiting policies in API documentation
The middleware intercepts incoming requests and validates the session token before forwarding to the handler.
When to use it: Explaining middleware behavior in architecture documentation
For backward compatibility, the legacy endpoint will remain available until December 2026, after which it will be permanently removed.
When to use it: Communicating a deprecation timeline in documentation
The error handling strategy uses a centralized error boundary that catches unhandled exceptions and logs them to our monitoring service.
When to use it: Describing error handling architecture in technical docs
Refer to the sequence diagram below for a visual overview of the request-response lifecycle.
When to use it: Referencing a diagram in architecture documentation
When contributing to this project, please follow the coding style guide and ensure all tests pass before submitting a pull request.
When to use it: Writing contribution guidelines for an open-source project
This release includes performance improvements, bug fixes, and a new caching layer that reduces average response time by 40%.
When to use it: Writing release notes summarizing changes
Ensure that all public methods have proper documentation comments including parameter descriptions, return types, and possible exceptions.
When to use it: Setting documentation standards in a contributing guide
Let's create an Architecture Decision Record for the database migration strategy.
When to use it: When making an important architectural decision that should be recorded for future reference
The runbook needs a section on how to handle database failover.
When to use it: When updating operational documentation for incident response
I documented the design decision to use event sourcing instead of traditional CRUD.
When to use it: When recording an important architectural choice for future reference
The sequence diagram shows how the payment flow interacts with the notification service.
When to use it: Describing a technical diagram in architectural documentation
The auto-generated docs from the OpenAPI spec are missing response examples.
When to use it: When reviewing automatically generated API documentation for completeness
The ADR documents the tradeoffs between using a monolith and a microservices architecture.
When to use it: Explaining the content of a specific Architecture Decision Record
The runbook includes step-by-step instructions for scaling the cluster during peak traffic.
When to use it: Describing operational documentation content for handling high-traffic events
The entity-relationship diagram in our docs needs to reflect the new foreign key constraints.
When to use it: When database schema documentation is out of sync with actual schema changes
The onboarding doc explains our branching strategy, code review process, and deployment pipeline.
When to use it: Describing comprehensive onboarding documentation for new hires
We maintain a decision log so future developers understand why certain tradeoffs were made.
When to use it: Explaining the purpose of keeping architectural decision records
The database schema documentation should include column types, constraints, and index definitions.
When to use it: Specifying what a complete database schema document should contain
Our docs-as-code approach means documentation lives in the same repository as the source code.
When to use it: Explaining the team's documentation philosophy to a new team member
The postmortem report should be added to our incident response knowledge base.
When to use it: After resolving an incident and wanting to document lessons learned
The contributing guide requires all code examples in documentation to be tested in continuous integration.
When to use it: Establishing quality standards for documentation code snippets
Self-documenting code reduces the need for comments, but it does not eliminate the need for high-level documentation.
When to use it: Discussing the balance between code readability and written documentation
The sequence diagram description clarifies the order of service calls during the checkout process.
When to use it: Explaining what a sequence diagram communicates in system architecture documentation
The migration guide covers backward-incompatible changes and provides code snippets for each fix.
When to use it: Describing a comprehensive migration document for a major library update
Document the retry behavior and timeout values for each third-party integration.
When to use it: Requesting documentation of resilience configuration for external service calls
We adopted Diátaxis as our documentation framework, separating tutorials from reference material.
When to use it: Explaining the organizational framework used for structuring documentation
The architecture documentation uses C4 model diagrams to show system context, containers, and components.
When to use it: Describing the visualization approach used in architecture documentation
The API versioning strategy and sunset policy are clearly outlined in the developer portal.
When to use it: Pointing to documentation about API lifecycle management
The data flow diagram in the architecture docs should show how events propagate through the message queue.
When to use it: Requesting specific technical detail in architecture documentation
The OpenAPI specification file serves as both the contract and the documentation for our REST endpoints.
When to use it: Explaining how the API specification doubles as documentation
We should document the expected behavior when the circuit breaker opens for downstream services.
When to use it: Requesting documentation about resilience patterns in the system architecture
The contributing guidelines now require a documentation impact assessment for each feature pull request.
When to use it: Introducing a new process to ensure documentation stays current with feature development
The webhook documentation must specify the payload format, retry policy, and expected response codes.
When to use it: Defining completeness requirements for webhook integration documentation
The ADR should capture the context, the decision itself, and the consequences both positive and negative.
When to use it: Explaining the proper structure of an Architecture Decision Record
We embedded runnable code examples in our documentation using interactive code playgrounds.
When to use it: Describing an advanced documentation feature for developer experience
Before shipping the breaking change, we need to send a deprecation email and update the migration docs.
When to use it: Planning communication around a breaking change in a public API
Documentation should be treated as a first-class deliverable, not an afterthought tacked on at the end of a sprint.
When to use it: Advocating for prioritizing documentation work during sprint planning
The architecture decision record explains why we chose this approach
When to use it: Referencing ADRs
The migration guide should cover breaking changes step by step
When to use it: Writing upgrade documentation
The runbook describes how to handle production incidents
When to use it: Operations documentation
We need to document the authentication flow with examples
When to use it: Security documentation
The deployment guide covers all the steps from staging to production
When to use it: Deployment process documentation
We should document the retry policy for failed API calls
When to use it: Documenting resilience patterns
The documentation should explain the rationale behind each design decision
When to use it: Documenting the why, not just the what
The API versioning strategy is explained in the developer guide
When to use it: Referencing versioning docs
The security documentation should cover threat models and mitigations
When to use it: Security-focused documentation
The performance benchmarks should be documented for each release
When to use it: Tracking performance metrics in docs
I documented the caching strategy and invalidation rules
When to use it: Cache architecture documentation
The monitoring and alerting setup is documented in the ops guide
When to use it: Operations documentation
The SLA documentation specifies uptime and response time guarantees
When to use it: Service level agreement documentation
We should document the backup and recovery procedures
When to use it: Disaster recovery documentation
The error handling guide documents how errors propagate through layers
When to use it: Error handling architecture documentation
The network layer documentation explains the request pipeline
When to use it: Documenting network architecture
The infrastructure as code templates are documented in the DevOps guide
When to use it: Infrastructure documentation
The compliance documentation tracks all regulatory requirements we meet
When to use it: Regulatory compliance docs
The load testing results should be attached to the documentation
When to use it: Performance test documentation
Can you document the data retention policy for user information?
When to use it: Privacy policy documentation
I created a decision matrix for the technology selection
When to use it: Technology evaluation documentation
We should include network topology diagrams in the infrastructure docs
When to use it: Network architecture documentation
The incident postmortem should be documented with root cause analysis
When to use it: Post-incident documentation
The event bus documentation should list all published and consumed events
When to use it: Event-driven architecture docs
The rollback procedure is documented in case we need to revert
When to use it: Rollback documentation
Let's add a diagram showing the microservices communication patterns
When to use it: Microservices architecture docs
The capacity planning document estimates resource needs for scaling
When to use it: Scaling documentation
The schema migration documentation should explain how to rollback each step
When to use it: Database migration docs
The documentation should include a section on error recovery procedures
When to use it: Error recovery documentation
I added a section on how to handle sensitive data according to our policy
When to use it: Data handling documentation
The observability documentation covers logging, metrics, and tracing
When to use it: Observability stack documentation
I documented all the third-party service integrations and their SLAs
When to use it: Third-party service documentation
I created a documentation health dashboard to track coverage and freshness
When to use it: Documentation metrics
We documented the queue processing logic with throughput expectations
When to use it: Queue system documentation
We should document the database indexing strategy for query optimization
When to use it: Database optimization documentation
The documentation clearly explains how to extend the plugin system
When to use it: Plugin architecture documentation
We should document the event sourcing patterns used in the system
When to use it: Event sourcing documentation
Can you document the message queue consumer retry behavior?
When to use it: Message queue documentation
The documentation should explain the caching invalidation strategy we use
When to use it: Cache invalidation documentation
We need to document the graceful shutdown procedure for the service
When to use it: Service lifecycle documentation
We documented the input sanitization rules to prevent injection attacks
When to use it: Security best practices documentation
Other everyday developer situations
- Daily standup280 phrases
- Code review275 phrases
- Pull requests300 phrases
- Bug reports300 phrases
- Meetings300 phrases
- Job interviews300 phrases
- Slack and chat300 phrases
- Email298 phrases
- Technical discussions299 phrases
- Polite phrases300 phrases
- Pair programming300 phrases
Guides with more context
Take it to your phone
In the Devlingo app you get 10 new phrases a day, each with real-world context, pronunciation and examples, and the widget shows the phrase of the day on your iPhone Home Screen.