The other day, I was looking at a software spec from a client. This document was at least a dozen pages, three spent outlining data types, and a few whole sections consisting of paragraphs of text describing the form and function of a software project.

From my standpoint, sitting at my editor and about to write some code, this is useless. What would be awesome is a spec that just outlined the steps a user would take when using the software, like so:

1. Login using their Windows login information.
2. From a table of daily report data, select the rows that should not be in the report and click “Suppress.”
3. Review the suppressed rows for accuracy, and confirm suppression
4. Software emails the report data, minus the suppressed rows, to reports@example.com

Maybe, maybe, add a section of possible edge cases: “This may fail when confronted with x“, or, “We need the ability to proceed without selecting any rows for suppression.”

That’s it. Two pages max. If your manager needs a summary of the project that should be in a separate document, not crammed into the one I’m trying to use to develop your tool. And the only time I should ever see a table of datatypes for the application is if I need to accept data from or export data to an external system. If I never need to do that, please do not design my database for me. I can do that myself, and I have a highly-paid, skillful, SQL-fu master of a DBA to correct me if I fail.

And, seriously, cut out the “sign for approval” crap. We used to do this at Innova, way back in the early days (thankfully before my time here). We’d design these thick, verbose, nasty documents full of weasel words like “in most cases”, “usually”, and “as approved by x“, and then we made our client sign off on it. The only purpose that document served is to shift blame from us to the client — if something went wrong with the program, we can point to a signed statement and proclaim “but you signed off on it!” Luckily Innova is in a place right now where we don’t need to scrape for clients, and the only clients that need (or like) that sort of thing are clients we don’t want anyway.

Bottom-line: software requirements documents should list only the requirements of the software (shock), and not pointless crap designed to appease managers or shift blame to clients. There are environments where that kind of overhead is required, and this isn’t one of them.

…end rant.