I posted an Agile LinkedIn discussion group question Where do you go to see what the code really does besides asking a developer to start a discussion about the role of specifications in the new Agile methodology. The discussion threads have been interesting and lively (LinkedIn, group “Agile”). So I wanted to answer the question posed numerous times: “Who would use that documentation and why/how?”

First, I’m not talking about old, antiquated waterfall design specs that are soon out-of-date used by no one. I’m talking about living, breathing hierarchical information (in a central tool accessible by everyone) that represent the repository of product knowledge: protected, validated, for use by the entire organization. Documents that everyone in the organization takes ownership in and uses. A cool set of “shiny docs”.

I can answer later how it could have been done (seems it’s not done at most companies and recent surveys say 83% of companies at best use Word Docs to describe their requirements) – but for argument’s sake, trust and believe there is a repository on-line specifications (“shiny docs”).

Who uses our current on-line specs and why do they need them?
a) For the developers – for the new guy, not as a replacement for training and not a static user manual – rather a handy reference area to delve into for more detailed, complex functional understanding, even some design details. A wiki for the product, helpful even for the most experienced developers.

b) Technical Support (TS) (the Call Center) wants to be able to quickly identify if a customer request is a bug, training issue, or if it should become a new feature request. They do their initial investigation using the specifications and replicate the issue in-house if they believe it’s a bug (so they help identify if it’s a customer config problem or base code). For non-bugs, they use them to understand how the product was designed versus what the customer is requesting to give better feedback to the PMs and better represent the customer’s business position for the change versus what’s there. Having a knowledgeable TS team that can get accurate information about all features in a very large enterprise application streamlines getting real bugs and issues into the product development releases. It’s much quicker if everyone knows/agrees a fix is needed than if something just sits on the backlog pile until the next PM release review cycle. Customer satisfaction is improved with clear feedback about if a ‘fix’ is feasible and how quickly. Some product changes can’t be immediate. Customers get that. Clear communication either way improves customer satisfaction.

c) The Product Management Team: If you are a Product Manager for a huge enterprise application and need to add new features and functions requested by customers to an older module with tons of business functionality, you probably don’t know everything about what the product does or even all of the history about what it should do and why customers wanted it that way. The online specifications help immensely.

If such documentation could be produced automatically as the result of the development process – wouldn’t it be useful? Why not aim for that?