English for developers · Documentation

Software documentation phrases for READMEs and docs

Quick answer

Writing docs gets easier with model sentences: how to install, how to use, what each parameter does, what changed in the release. We picked 300 software documentation phrases from the Devlingo app for READMEs, API docs, comments and changelogs, each with context and audio.

Updated

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)

  1. Please refer to the README for setup instructions.

    When to use it: Directing someone to the project README file

  2. This function returns a list of active users.

    When to use it: Writing an inline comment describing a function's return value

  3. See the changelog for a list of recent updates.

    When to use it: Pointing someone to the changelog file

  4. Make sure to update the docs before merging.

    When to use it: Reminding a teammate to keep documentation in sync with code changes

  5. This endpoint accepts a JSON body with the following fields.

    When to use it: Documenting an API endpoint's request format

  6. Add a brief description of your changes to the pull request.

    When to use it: Asking someone to document their PR properly

  7. I'll add code comments to explain the business logic.

    When to use it: Committing to document complex business rules in the code

  8. 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

  9. 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

  10. 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

  11. 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

  12. 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

  13. 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

  14. 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

  15. 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

  16. 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

  17. 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

  18. 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

  19. 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

  20. 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

  21. 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

  22. Avoid using TODO comments as a substitute for proper task tracking.

    When to use it: Advising against overreliance on code comments for project management

  23. 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

  24. 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

  25. 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

  26. The how-to guide should include common pitfalls and their solutions.

    When to use it: Improving a how-to guide with troubleshooting information

  27. 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

  28. Add a prerequisites section to the setup guide listing required software versions.

    When to use it: Improving setup documentation with dependency information

  29. 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

  30. 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

  31. 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

  32. 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

  33. 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

  34. 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

  35. 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

  36. 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

  37. 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

  38. 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

  39. 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

  40. We maintain separate getting-started guides for mobile developers and backend developers.

    When to use it: Describing audience-specific documentation for different developer personas

  41. 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

  42. 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

  43. The README should include setup instructions for new developers

    When to use it: Onboarding documentation

  44. The changelog needs to be updated before the release

    When to use it: Release documentation process

  45. This function is missing its documentation comment

    When to use it: Adding inline code documentation

  46. The glossary helps new team members understand our terminology

    When to use it: Creating a project glossary

  47. Can you review the inline comments for accuracy?

    When to use it: Reviewing code comments

  48. The user guide needs screenshots of the latest interface

    When to use it: Updating visual documentation

  49. I added a prerequisites section at the top of the guide

    When to use it: Setting up documentation structure

  50. The contributing guide outlines how to submit pull requests

    When to use it: Open source contribution documentation

  51. Let's create a FAQ section based on the most asked questions

    When to use it: Building FAQ documentation

  52. The style guide ensures consistency across the documentation

    When to use it: Documentation standards

  53. The release notes should highlight new features and bug fixes

    When to use it: Writing release documentation

  54. The parameter description is missing from the function header

    When to use it: Completing function documentation

  55. The onboarding documentation should include common pitfalls

    When to use it: Helping new team members avoid mistakes

  56. The README badges show the build status and test coverage

    When to use it: Adding status badges to documentation

  57. Let's document the environment variables required to run the app

    When to use it: Configuration documentation

  58. Let's add a table of contents to make the document easier to navigate

    When to use it: Improving documentation navigation

  59. Please update the installation instructions for the latest version

    When to use it: Keeping setup docs current

  60. We should add cross-references between related documentation pages

    When to use it: Linking documentation together

  61. The code review checklist should be part of the documentation

    When to use it: Standardizing review processes

  62. Let's keep the documentation language simple and avoid jargon

    When to use it: Writing accessible documentation

  63. Let's add a known issues section to the release notes

    When to use it: Documenting known limitations

  64. Can you proofread the documentation for grammar and spelling?

    When to use it: Documentation quality review

  65. I added a section on how to run the project locally

    When to use it: Local development documentation

  66. Can you add a comparison table between the free and premium features?

    When to use it: Feature comparison documentation

  67. Let's create a cheat sheet with the most common commands

    When to use it: Quick reference documentation

  68. The coding standards document should be the first thing new developers read

    When to use it: Establishing coding conventions

  69. Let's add a section about the development workflow and branching strategy

    When to use it: Git workflow documentation

  70. Let's create a video walkthrough for the complex setup process

    When to use it: Creating video documentation

  71. The documentation template standardizes how we write new guides

    When to use it: Documentation templates

  72. Can you add sequence numbers to the API workflow steps?

    When to use it: Ordering documentation steps

  73. The documentation should specify which platforms are supported

    When to use it: Platform compatibility docs

  74. Can you write a brief summary at the top of each documentation page?

    When to use it: Documentation readability improvement

  75. The documentation review is part of our definition of done

    When to use it: Documentation as quality gate

  76. I added a troubleshooting flowchart to help diagnose common problems

    When to use it: Visual troubleshooting guides

  77. The documentation should explain the difference between each log level

    When to use it: Logging documentation

  78. Let's create a visual guide for the entire user journey

    When to use it: User experience documentation

  79. The documentation should link to the related Jira tickets for context

    When to use it: Connecting docs to project management

  80. Can you add a section explaining the conventions used throughout the docs?

    When to use it: Documentation meta-information

  81. The API documentation clearly distinguishes between required and optional fields

    When to use it: API field documentation

  82. The API documentation should include curl examples for quick testing

    When to use it: Adding practical API examples

  83. The documentation portal should have a feedback mechanism for readers

    When to use it: Documentation feedback loop

  84. The documentation should include a system requirements section

    When to use it: System prerequisites documentation

  85. We should add a decision tree for choosing the right component

    When to use it: Component selection guide

  86. The documentation should include a section on how to report security issues

    When to use it: Security reporting documentation

  87. The documentation portal has a dark mode toggle for better readability

    When to use it: Documentation UX improvement

  88. Let's add a list of all the environment variables with their descriptions

    When to use it: Environment variable reference

  89. The documentation uses consistent terminology throughout all sections

    When to use it: Documentation consistency

  90. Let's create a glossary of abbreviations used in the codebase

    When to use it: Abbreviation reference documentation

  91. The documentation includes a compatibility matrix for browser and OS support

    When to use it: Compatibility documentation

  92. The API documentation should group endpoints by resource type

    When to use it: API documentation organization

  93. I created a reference card summarizing the most important configuration values

    When to use it: Quick reference documentation

  94. 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)

  1. We should document the environment variables required to run the project.

    When to use it: Suggesting adding configuration documentation

  2. 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

  3. This section covers the migration steps from version 2 to version 3.

    When to use it: Writing a migration guide introduction

  4. 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

  5. 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

  6. Please include a code example showing how to initialize the SDK.

    When to use it: Requesting a usage example in documentation

  7. 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

  8. Authentication is handled via JWT tokens passed in the Authorization header.

    When to use it: Explaining the authentication mechanism in API docs

  9. The troubleshooting section addresses the most commonly reported issues and their solutions.

    When to use it: Introducing the troubleshooting section of a guide

  10. 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

  11. The API docs are missing examples for the authentication endpoints.

    When to use it: When reviewing API documentation and finding incomplete sections

  12. This function is complex enough to warrant a detailed docstring.

    When to use it: During code review when a complex function lacks proper documentation

  13. 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

  14. 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

  15. 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

  16. 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

  17. 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

  18. 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

  19. 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

  20. 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

  21. 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

  22. We use JSDoc annotations to generate our TypeScript library documentation.

    When to use it: Explaining the documentation tooling used in a JavaScript/TypeScript project

  23. 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

  24. 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

  25. 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

  26. The Swagger UI lets developers test API endpoints interactively from the documentation.

    When to use it: Explaining the benefits of interactive API documentation

  27. 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

  28. I set up a documentation linter to catch broken links and formatting issues automatically.

    When to use it: Implementing automated quality checks for documentation

  29. We need to version our API documentation separately from the codebase.

    When to use it: Discussing documentation versioning strategy for a public API

  30. 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

  31. 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

  32. 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

  33. 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

  34. 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

  35. 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

  36. We track documentation coverage the same way we track code coverage.

    When to use it: Describing a mature documentation practice with metrics and accountability

  37. 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

  38. 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

  39. 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

  40. 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

  41. Make sure to cross-reference related documentation pages so readers can find additional context.

    When to use it: Improving documentation navigation through internal linking

  42. 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

  43. We automated the deployment of our documentation site using a continuous integration pipeline.

    When to use it: Describing the documentation deployment infrastructure

  44. 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

  45. 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

  46. 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

  47. 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

  48. 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

  49. Can you add a code example to this API reference?

    When to use it: Enhancing API documentation

  50. We should document the error codes and their meanings

    When to use it: Creating error reference documentation

  51. Please add the return type description to the docstring

    When to use it: Completing function documentation

  52. I wrote a troubleshooting section for the most common issues

    When to use it: Creating self-service support docs

  53. The API endpoint documentation is outdated and needs a refresh

    When to use it: Updating stale documentation

  54. Let's add a sequence diagram to explain this workflow

    When to use it: Using visual diagrams in documentation

  55. The configuration options should be documented with default values

    When to use it: Documenting configurable settings

  56. We need to add deprecation notices to the old API methods

    When to use it: Marking deprecated functionality

  57. The documentation should be versioned alongside the code

    When to use it: Documentation versioning strategy

  58. We should add type annotations to improve the documentation clarity

    When to use it: Using type information for documentation

  59. This technical specification needs peer review before publishing

    When to use it: Documentation review process

  60. I documented the data model relationships in a diagram

    When to use it: Creating data model documentation

  61. Can you write a quick start guide for the SDK?

    When to use it: Creating getting started documentation

  62. Let's use Swagger to generate the API documentation automatically

    When to use it: Automated documentation tools

  63. I noticed the code samples in the docs don't compile anymore

    When to use it: Maintaining documentation accuracy

  64. We should add a data dictionary for the database tables

    When to use it: Database documentation

  65. The API rate limits should be clearly documented for consumers

    When to use it: Documenting API constraints

  66. I created a decision log to track our architectural choices

    When to use it: Recording project decisions

  67. The class diagram needs to be updated after the refactoring

    When to use it: Keeping diagrams in sync with code

  68. Can you add usage examples for each public method?

    When to use it: Creating comprehensive method documentation

  69. I wrote a tutorial that walks through building a feature from scratch

    When to use it: Creating tutorial documentation

  70. The testing strategy document outlines our quality assurance approach

    When to use it: QA documentation

  71. I added examples showing both success and error response formats

    When to use it: Documenting API response formats

  72. The webhook documentation needs to include payload examples

    When to use it: Documenting webhook integrations

  73. We documented the design system with component specifications

    When to use it: Design system documentation

  74. The dependency list should include version requirements and licenses

    When to use it: Documenting project dependencies

  75. The documentation should include accessibility guidelines for the UI

    When to use it: Accessibility documentation

  76. We need to update the architecture overview after adding the new service

    When to use it: Maintaining system architecture docs

  77. The API changelog tracks all breaking and non-breaking changes

    When to use it: API change management documentation

  78. The integration guide explains how to connect with third-party services

    When to use it: Third-party integration documentation

  79. Let's document the feature flags and how they affect behavior

    When to use it: Feature flag documentation

  80. The data flow documentation shows how information moves through the system

    When to use it: System data flow documentation

  81. The API documentation should include request and response headers

    When to use it: Complete API documentation

  82. I documented the localization workflow for adding new languages

    When to use it: Internationalization process documentation

  83. We need inline documentation for the complex business logic

    When to use it: Documenting domain-specific code

  84. Can you update the entity relationship diagram with the new tables?

    When to use it: Maintaining database diagrams

  85. The documentation search needs to be indexed for better discoverability

    When to use it: Improving documentation search

  86. We should keep a log of all the technical debt we identify

    When to use it: Technical debt tracking docs

  87. The API sandbox documentation helps developers test without affecting production

    When to use it: Sandbox environment docs

  88. The auto-generated documentation needs manual review for accuracy

    When to use it: Validating auto-generated docs

  89. The API pagination documentation should show cursor-based and offset examples

    When to use it: Pagination documentation

  90. Let's add interactive code samples that readers can run directly

    When to use it: Interactive documentation

  91. I documented the design tokens used across the component library

    When to use it: Design token documentation

  92. We need to document the data validation rules for each input field

    When to use it: Input validation documentation

  93. The documentation needs to be accessible to non-technical stakeholders

    When to use it: Writing for mixed audiences

  94. I updated the API documentation to reflect the new response format

    When to use it: Keeping API docs in sync

  95. We should document how the cron jobs are scheduled and monitored

    When to use it: Scheduled jobs documentation

  96. The component storybook serves as living documentation for the UI

    When to use it: UI component documentation

  97. Can you document the environment-specific configuration differences?

    When to use it: Environment configuration docs

  98. The documentation should clearly state the supported authentication methods

    When to use it: Authentication documentation

  99. We need to keep the API mock server responses in sync with the documentation

    When to use it: Mock server documentation consistency

  100. The documentation build system checks for broken links automatically

    When to use it: Documentation CI/CD

  101. I documented the notification system with all trigger conditions

    When to use it: Notification system documentation

  102. Can you document the differences between the development and production builds?

    When to use it: Build configuration documentation

  103. Let's consolidate the scattered documentation into a single source of truth

    When to use it: Documentation centralization

  104. The permission matrix shows which roles can access each feature

    When to use it: Access control documentation

  105. We need a clear diagram of the state transitions in this workflow

    When to use it: State machine documentation

  106. The documentation versioning follows semantic versioning alongside the codebase

    When to use it: Version-aligned documentation

  107. The documentation should include performance optimization tips for developers

    When to use it: Performance best practices docs

  108. Let's document the feature toggle naming conventions for consistency

    When to use it: Feature flag naming documentation

  109. The analytics event documentation maps each event to its business purpose

    When to use it: Analytics tracking documentation

  110. We should document the CI pipeline stages and what each one validates

    When to use it: CI/CD pipeline documentation

  111. Let's document the error codes with actionable resolution steps

    When to use it: Error resolution documentation

  112. The API documentation includes rate limit headers in the response examples

    When to use it: Rate limit documentation details

  113. I documented the test data generation process and seed scripts

    When to use it: Test data documentation

  114. Let's document the edge cases that the validation layer handles

    When to use it: Validation logic documentation

  115. The documentation should explain how the feature flag evaluation works

    When to use it: Feature flag evaluation documentation

  116. Can you create a mapping between the old and new API endpoints?

    When to use it: API migration mapping documentation

  117. I added annotations to the architecture diagram explaining each layer

    When to use it: Annotated architecture diagrams

  118. The SDK documentation includes getting started guides for each platform

    When to use it: Multi-platform SDK docs

  119. The documentation should warn about known limitations of the current implementation

    When to use it: Limitation documentation

  120. I documented the health check endpoints and their expected responses

    When to use it: Health check endpoint documentation

  121. The documentation should specify the maximum payload size for each endpoint

    When to use it: API constraints documentation

  122. Let's add a section on how the feature was designed and why

    When to use it: Design rationale documentation

  123. The documentation maps each microservice to its owning team

    When to use it: Service ownership documentation

  124. The documentation should include a dedicated section for mobile-specific behavior

    When to use it: Platform-specific documentation

  125. The documentation explains how to set up local development with Docker

    When to use it: Docker setup documentation

Advanced phrases (81)

  1. 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

  2. The module exports a singleton instance that should be initialized once during application startup.

    When to use it: Documenting initialization requirements for a module

  3. 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

  4. 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

  5. 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

  6. 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

  7. 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

  8. 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

  9. 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

  10. 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

  11. 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

  12. The runbook needs a section on how to handle database failover.

    When to use it: When updating operational documentation for incident response

  13. 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

  14. The sequence diagram shows how the payment flow interacts with the notification service.

    When to use it: Describing a technical diagram in architectural documentation

  15. The auto-generated docs from the OpenAPI spec are missing response examples.

    When to use it: When reviewing automatically generated API documentation for completeness

  16. 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

  17. 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

  18. 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

  19. The onboarding doc explains our branching strategy, code review process, and deployment pipeline.

    When to use it: Describing comprehensive onboarding documentation for new hires

  20. 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

  21. 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

  22. 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

  23. 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

  24. 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

  25. 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

  26. 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

  27. 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

  28. 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

  29. 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

  30. 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

  31. 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

  32. 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

  33. 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

  34. 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

  35. 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

  36. 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

  37. 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

  38. We embedded runnable code examples in our documentation using interactive code playgrounds.

    When to use it: Describing an advanced documentation feature for developer experience

  39. 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

  40. 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

  41. The architecture decision record explains why we chose this approach

    When to use it: Referencing ADRs

  42. The migration guide should cover breaking changes step by step

    When to use it: Writing upgrade documentation

  43. The runbook describes how to handle production incidents

    When to use it: Operations documentation

  44. We need to document the authentication flow with examples

    When to use it: Security documentation

  45. The deployment guide covers all the steps from staging to production

    When to use it: Deployment process documentation

  46. We should document the retry policy for failed API calls

    When to use it: Documenting resilience patterns

  47. The documentation should explain the rationale behind each design decision

    When to use it: Documenting the why, not just the what

  48. The API versioning strategy is explained in the developer guide

    When to use it: Referencing versioning docs

  49. The security documentation should cover threat models and mitigations

    When to use it: Security-focused documentation

  50. The performance benchmarks should be documented for each release

    When to use it: Tracking performance metrics in docs

  51. I documented the caching strategy and invalidation rules

    When to use it: Cache architecture documentation

  52. The monitoring and alerting setup is documented in the ops guide

    When to use it: Operations documentation

  53. The SLA documentation specifies uptime and response time guarantees

    When to use it: Service level agreement documentation

  54. We should document the backup and recovery procedures

    When to use it: Disaster recovery documentation

  55. The error handling guide documents how errors propagate through layers

    When to use it: Error handling architecture documentation

  56. The network layer documentation explains the request pipeline

    When to use it: Documenting network architecture

  57. The infrastructure as code templates are documented in the DevOps guide

    When to use it: Infrastructure documentation

  58. The compliance documentation tracks all regulatory requirements we meet

    When to use it: Regulatory compliance docs

  59. The load testing results should be attached to the documentation

    When to use it: Performance test documentation

  60. Can you document the data retention policy for user information?

    When to use it: Privacy policy documentation

  61. I created a decision matrix for the technology selection

    When to use it: Technology evaluation documentation

  62. We should include network topology diagrams in the infrastructure docs

    When to use it: Network architecture documentation

  63. The incident postmortem should be documented with root cause analysis

    When to use it: Post-incident documentation

  64. The event bus documentation should list all published and consumed events

    When to use it: Event-driven architecture docs

  65. The rollback procedure is documented in case we need to revert

    When to use it: Rollback documentation

  66. Let's add a diagram showing the microservices communication patterns

    When to use it: Microservices architecture docs

  67. The capacity planning document estimates resource needs for scaling

    When to use it: Scaling documentation

  68. The schema migration documentation should explain how to rollback each step

    When to use it: Database migration docs

  69. The documentation should include a section on error recovery procedures

    When to use it: Error recovery documentation

  70. I added a section on how to handle sensitive data according to our policy

    When to use it: Data handling documentation

  71. The observability documentation covers logging, metrics, and tracing

    When to use it: Observability stack documentation

  72. I documented all the third-party service integrations and their SLAs

    When to use it: Third-party service documentation

  73. I created a documentation health dashboard to track coverage and freshness

    When to use it: Documentation metrics

  74. We documented the queue processing logic with throughput expectations

    When to use it: Queue system documentation

  75. We should document the database indexing strategy for query optimization

    When to use it: Database optimization documentation

  76. The documentation clearly explains how to extend the plugin system

    When to use it: Plugin architecture documentation

  77. We should document the event sourcing patterns used in the system

    When to use it: Event sourcing documentation

  78. Can you document the message queue consumer retry behavior?

    When to use it: Message queue documentation

  79. The documentation should explain the caching invalidation strategy we use

    When to use it: Cache invalidation documentation

  80. We need to document the graceful shutdown procedure for the service

    When to use it: Service lifecycle documentation

  81. We documented the input sanitization rules to prevent injection attacks

    When to use it: Security best practices documentation

Other everyday developer situations

← English for developers

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.

Frequently asked questions

What people ask most about this, answered with the source.

How do you write a README?
Fixed sections: Overview, Installation, Usage, Configuration and Contributing, with an opening sentence saying what the project does.
Which tense should documentation use?
Present to describe (returns, accepts) and imperative for instructions (install, run).
DevlingoLearn tech phrases & speaking
Use without installingGet