10 Organizing the documentation
This chapter covers
- The difference between user stories and features
- Keeping feature files focused
- Tracking domain terminology in a glossary
- How to use Gherkin tags
- Why journey scenarios matter
- Organizing your documentation
- Audience specific documentation
There’s no inherent restriction on the size of a feature file, but that doesn’t mean you should allow them to grow indefinitely. Each file illustrates the behavior of some part of the system and will act as documentation for as long as the system is in use. It’s therefore essential to structure your feature files in a way that makes them easy to consult and maintain, which includes making sure that they remain focused.
As your collection of feature files grows, it can become a mess of files that are hard to manage and maintain if left unorganized. Since Gherkin feature files are simple text files that live in your organization’s file system (and source control), you can use the techniques that you already know for structuring hierarchies of folders and files.
The team doesn’t have that many feature files yet, and they aren’t very large either, but it’s time that for them to take a look at what they do have and begin to create a meaningful structure. This will doubtless develop over time, but it’s easier to start early and review often rather than wait until the team becomes overwhelmed by the quantity and size of its feature files.