documentation-driven-development

To keep unit tests aligned with documentation, update the documentation first to reflect the new behavior, then modify the corresponding tests. This documentation-led change process ensures tests verify the documented behavior and fail loudly when implementation diverges.

Documentation-driven development is a practice where features are documented from the user's perspective before any code is written. Use it when building new features or modifying existing behavior to prevent undocumented or incorrectly documented capabilities from drifting into your product.

Write unit tests that directly reflect the documented behavior so mismatches fail loudly. By creating tests that guarantee documentation accuracy over time, you ensure that any divergence between the implementation and the written descriptions triggers a test failure.

Yes, documentation-driven development fits workflows modifying existing behavior. When changing an existing feature, you update the documentation first and then adjust the corresponding tests, ensuring the implementation stays aligned with the updated written descriptions.

Structure documentation using a framework like Divio's tutorial, how-to, reference, and explanation categories. Applying these reference materials alongside Markdown style guidance keeps docs consistent, clear, and discoverable for users before you start implementing the feature.

Undocumented behavior drifts into production when features are implemented without prior written descriptions. Enforcing documentation-first development prevents this by requiring updates to documentation before code, ensuring features are only considered real when users can find and trust written descriptions.