This is more of a “what I’m thinking” post than something full of good information. I am trying to frame my idea of feature specifications and I need to answer some questions. This seemed like as good a place as any to store my questions, but you are more than welcome to provide answers and opinions.

How to Organize Feature Documentation

You can have a feature that spans multiple systems. For example, a feature named Manage Orders can be implemented on the public facing customer website, the internal customer service website, the services that manage that data for both sites, and many other helper and core projects. Where do you document the feature? Do you do separate documents for each system? One master document for the feature that covers all systems? One document per team that manages the systems?

Where to Store Feature Documentation

Do you use Word Documents and store them in a shared drive or source control? Do you store them in a file repository or document management system? Maybe use a system that only stores the data associated with features that builds the actual documents on the fly? This could provide a better means of traceability and history than files.

Feature Documentation Detail

How detailed should feature documentation be? I mean we are supposed to be Agile Warriors who hate the old Waterfall Guard and their get all the requirement up front mantra, but we have to have some level of documentation to let us have a shared vision of what we are building. How do we record the vision and how much information do we capture? How do we get sign off on the vision? Should UAT be a part of the vision, say as a BDD style spec?

Automated Tests

Tests are also a part of specification. It seems like most errors I fix are in the presentation layer or integration (talking to db, file system…). Most errors can be sensed in functional UI tests or code integration tests. Do I need unit tests? Don’t kill me, the questions has to be asked. If I can adequately cover specs without unit tests, why attempt for so much unit test coverage? Maybe I should only use unit tests when I can’t cover some logic in a functional or integration test or when test maintenance or speed is just a lot better in a unit tests. I’m just asking it may be that unit tests still rock and there is no reason for me to change my stance on them, but I need to ask if there is an area to improve on this.