Technical documentation records what an application does, which business rules it applies, how users behave with it, and how its implementation works. In behavior-driven development, executable specifications provide documentation for stakeholders, while readable code and tests document technical behavior for developers. section 7.4.5 section 16.5.4
Effective documentation practices connect shared product understanding with maintainable implementation:
- Organize feature files around enduring product behavior rather than stories, iterations, or releases, because delivery boundaries do not reliably match product functionality. section 7.4.5
- Use readable, well-organized, annotated code together with executable unit and integration specifications to document low-level behavior. section 16.5.4
- For legacy systems, document critical or high-risk behavior first through behavior-focused tests, then expand coverage as understanding grows. section 16.6
A feature split across releases
Suppose development of one feature spans several iterations. Storing its scenarios under release directories can create duplication or uncertainty about where the feature belongs. Keeping the scenarios with the product behavior preserves documentation of the application rather than documentation of project delivery. section 7.4.5
