Software Specification Soup

March 20, 2007 11:05 AM

How do I get a handle on the hydra that is the set of software specifications I'm currently writing?

My boss has been telling me since I started my current job as a consultant last May that I need to write less-detailed specs. I was able to manage very detailed and complete specs on a project that lasted three months with a couple full time developers. That project was a success, and the customer is ready for us to roll out an upgrade.

Now I'm 7 months into another project for a different customer, have more developers on my team, and have around 250 pages of specifications that I've written for this project. They're getting out of hand. Every day the software is drifting farther from the specs. I don't have the time (or is it will?) to keep them in sync, and I'm in a huge writer's block situation. Why write more specs when the old ones are no longer up-to-date? I'm realizing, as my understanding of the domain and requirements grows, that some of my early documents are not well organized - some general rules are contained in specific documents, and some functionalities are grouped in less-than-perfect ways.

How can I get a handle on these specifications and avoid this problem in the future? Help!

posted by syzygy to computers & internet (8 comments total)

Can you delegate spec revision to the responsible engineers? Given how poorly many of us write you may be left with a hellish editing job instead but it might be worth a shot. You might need to institute policies that mandate spec revision and maintenance along with code development. It might also be easier if you enforce use of inline documentation such as doxygen, then use that to revise your specs.

Maybe your boss is right and they are too detailed. The up front planning in software is often short-sighted, so writing very detailed up front specs is arguably a waste of time. Paring them down might be an easier revision task than revamping them entirely.

Software is hard, it's why it pays well.
posted by chairface at 11:55 AM on March 20, 2007

Man, this topic fills a book. Here goes.

It seems pretty clear that you are lacking in a well developed software development process and experiencing a fair amount of scope creep. It may not be possible to rescue your situation without dismantling almost everything you (and your developers) have already done, but here are some suggestions for future development.

The firm I work for has an excellent process for software development and it follows the following pattern.

First, create a document describing your high-level operational concepts. This can consist of a white-paper, use-case diagram, etc. Something very high-level and general describing what your software is supposed to do.

Get all your stakeholders to review the document, make any revisions based on their feedback, get final approval, and then FREEZE the document.

DO NOT BEGIN SOFTWARE DEVELOPMENT AT THIS TIME.

Second, develop your requirements. There are many many books and training courses out there describing how this is best done. I recommend Ivy Hooks' stuff.

The essential idea is that you start at the highest level (more or less re-stating your operational concepts, but from the perspective of the system. i.e. "The System shall light a candle.") then do a little design to figure out how to compartmentalize your high level functionality (Match Handling subsystem, Candle Placement subsystem, Spent Match Disposal subsystem, etc.), then write some more requirements to flesh out the compartmentalization (The System shall use matches to light the candle.), then a little more design, and then some more requirements, until you have described everything that the system HAS TO DO AS REQUIRED BY THE CUSTOMER. While you develop your requirements, you must also concurrently develop test cases for each requirement so that you can prove that each requirement has been implemented correctly.

Some software development is permitted here, mostly to test out the feasibility of low level requirements, but anything that is generated here must be considered a prototype and expect to be thrown away.

When you have finalized your requirements, have them reviewed, revised, approved and FROZEN.

Finally, do your detailed design, based on your requirements. Here you will nail down exactly HOW you will do what you are REQUIRED to do. Every part of the design has to trace to a requirement. If you cannot trace it, then either there is a requirement missing, or the feature you are designing isn't required. Class hierarchies and method prototypes, etc. are devised at this point.

Review, Revise, Approve, Freeze. Some song and dance as before.

NOW, software development will begin.

Your developers need to look at your detailed design, and need to use the test cases you developed during requirements development. If you did all the previous steps correctly, you won't need to go back and change anything (which, obviously, can be costly).

Finally, after development is done, for each major feature, TEST THE HELL OUT OF IT using the Test Cases you developed during requirements.

If problems are found, make modifications, and test again. Rinse, repeat.

Good luck.
posted by Void_Ptr at 12:20 PM on March 20, 2007

An endlessly increasing spec is almost always the result of trying to bite off too big a deliverable in one go. Instead, think about defining incremental releases. How far away is your next planned release? The further away it is, the greater the chance of project failure. Also, when you're doing consulting, you want frequent milestones that give you an opportunity to make sure the client is happy with what you're doing, and provide an opportunity to bill for the completed part of the project earlier. The release doesn't necessarily have to be deployed at the customer, but it does have to be fully integrated and tested. That way, you can at least demo it to the people on the customer side who can judge whether the spec corresponds to their needs.

You already know how to deliver a 3-month project successfully; can you break this monster down into 3-month deliverables? You might want to step back, divide your high-level requirements into increments, and then follow something like Void_Ptr's process. First, get sign off on the overall release schedule and the features each release will support. Then focus on drilling down to detailed requirements only for the current increment. Get sign off on that, and only then can you start thinking about the detailed requirements for the next increment.
posted by fuzz at 3:02 PM on March 20, 2007

I've written functional specifications, but not for complex software. For whatever it's worth, I would try and break the project out into phased or component deliverables like Fuzz suggests. I've often found that as much as I want and need to do everything at once I can really only manage to do one thing right at a time.
posted by xammerboy at 3:59 PM on March 20, 2007

1. Hire a Project Manager.
2. Enforce the specs.
posted by mphuie at 5:40 PM on March 20, 2007

If a developer produces something that doesn't match the spec, then one of two things should happen:
1. The spec is immediately changed to correct discussed & agreed deficiencies
2. The developer gets told off and has to redo the work

Instead, I get the impression you're running alongside the project trying to document the chaos. The sensible thing to do would be to halt development, discuss the issues, and then move forward with a better approach and clarity about who's running the show.

Perhaps your documents aren't quite as good as they could be, and perhaps that's made it easier for developers to ignore them, but any drift in the project comes from problems with management and communication.
posted by malevolent at 3:16 AM on March 21, 2007

First off, thanks for the great tips here. Fuzz, I marked your answer the best because I feel that's a big part of the problem - I've been working on this project now for almost a year and we're now finally getting the customer to start setting some milestones. I have told them multiple times over the past few months that the project needs to be organized better, and into smaller, coherent chunks.

Right now, we're still in the mode of having started 100 different things and finished none of them, but we're trying to turn that around.

In the meantime, I've pared down my specs, and pared them down again, and my boss is finally pretty happy with the results - they're still pretty formal and well organized (as well organized as a large collection of long Word docs probably can be, with a reasonable amount of effort).

chairface: I've taken your advice, too. I have asked my developers to give me some feedback and they've pointed out some areas where I can cut out some unnecessary detail.

Void_Ptr: Also excellent advice, but it will never (or at least not in the scope of the current project) work with this customer. They're married to chaos, and seem to be doing ok, despite that fact. I have to find a way to live within their chaotic system.

malevolent: I'm working on keeping the docs updated to match actual events, but the more docs I create, the harder that is - especially with the older ones, which were, in fact, too detailed, and had too many pieces of info repeated in different locations.
posted by syzygy at 6:52 AM on July 17, 2007

Some thoughts from a guy who has just finished studying for his software engineering exam:

The process void_ptr describes is a variant of the so called waterfall process which basically has the advantage of a thorough planning stage, which can be beneficial, because bugfixing becomes exponentially more expensive along the way. It has the disadvantage though that is is not very well suited to incorporate changes in requirements. This leads to specs being out of date. Also, it is well known that testing specifications and software throughout the process (rather than just at the end) significantly improves software quality.

I would second fuzz's recommendation to adopt a more incremental or agile process.

Depending on your project and your environment, maybe you could adopt some of the Extreme Programming (XP) techniques. XP is a methodology which favors very quick iterations (around 3 weeks) over thorough planning. It doesn't use very formal specifications, but rather "user stories".
posted by Herr Fahrstuhl at 10:40 AM on July 17, 2007