Documenting Requirements
Almost every place I've worked struggles (in varying degrees) documenting business requirements. Maybe not the initial requirements, but the new requirements/enhancements that emerge as releases are delivered. They usually stem from a conversation that starts out, "I really like this, but it would be really cool if it could also do this other thing I had not thought of until now."
This is a bigger than normal issue at the place I'm currently working. Mostly it's because new requirements are not captured in the same documents as the original specification. Instead, a new document is created and placed into a shared folder on the network (or sometimes a series of different folders). Over time, there are a lot of distributed requirement documents and it's really difficult to figure out what the system is supposed to do (and where to look for this information). Please, place all your application requirements in a single coherent "document"! Make it stupid easy for people to figure out how the application is supposed to work. Right now the ramp up time to learn this application is ridiculously long and the poor state of these requirement documents are a big reason why.
I've used wiki's in the past to capture requirements and I think it worked out pretty well. My practice there was to create a new wiki page for each feature request and then link to that page from the 'overall specification' and 'version release notes' wiki pages. The one thing I've often wished for is a better way to link these pages to the source code changes. I made a practice of creating a bug ticket for each enhancement then cross-linking the ticket to the wiki page, and then using the bug ticket number in the code check-in comment. This process is cumbersome and somewhat difficult to work through in reverse - like finding all the code commits for a given ticket. I'd like it if this functionality were baked into source control systems (maybe it is and I don't know).
The second big problem with documentation on my current team is requirements ownership. The developers are reluctant to update the business requirement documents (I don't know why). The business team is extremely busy and updating these requirement documents is their lowest priority. It doesn't take a genius to see what's going to happen here.... developers start working on features before the requirements are documented and undocumented features are implemented.
Now, while the difficulty in finding the requirements in the first place was a big problem, having undocumented features in your application is a HUGE problem! This practice basically invalidates any documentation you do happen to find. All of a sudden you have no idea if previous requirements have verbally changed or which documented requirements override the verbal requirements that someone vaguely remembers. You have to be disciplined enough to document your requirements before implementing them! There is no excuse for not doing this. None.
This is a bigger than normal issue at the place I'm currently working. Mostly it's because new requirements are not captured in the same documents as the original specification. Instead, a new document is created and placed into a shared folder on the network (or sometimes a series of different folders). Over time, there are a lot of distributed requirement documents and it's really difficult to figure out what the system is supposed to do (and where to look for this information). Please, place all your application requirements in a single coherent "document"! Make it stupid easy for people to figure out how the application is supposed to work. Right now the ramp up time to learn this application is ridiculously long and the poor state of these requirement documents are a big reason why.
I've used wiki's in the past to capture requirements and I think it worked out pretty well. My practice there was to create a new wiki page for each feature request and then link to that page from the 'overall specification' and 'version release notes' wiki pages. The one thing I've often wished for is a better way to link these pages to the source code changes. I made a practice of creating a bug ticket for each enhancement then cross-linking the ticket to the wiki page, and then using the bug ticket number in the code check-in comment. This process is cumbersome and somewhat difficult to work through in reverse - like finding all the code commits for a given ticket. I'd like it if this functionality were baked into source control systems (maybe it is and I don't know).
The second big problem with documentation on my current team is requirements ownership. The developers are reluctant to update the business requirement documents (I don't know why). The business team is extremely busy and updating these requirement documents is their lowest priority. It doesn't take a genius to see what's going to happen here.... developers start working on features before the requirements are documented and undocumented features are implemented.
Now, while the difficulty in finding the requirements in the first place was a big problem, having undocumented features in your application is a HUGE problem! This practice basically invalidates any documentation you do happen to find. All of a sudden you have no idea if previous requirements have verbally changed or which documented requirements override the verbal requirements that someone vaguely remembers. You have to be disciplined enough to document your requirements before implementing them! There is no excuse for not doing this. None.
Comments