Musings of a Software Development Manager

M. Kenneth Clark

Monday, March 08, 2004

Functional and Technical Specs really work 

A few months ago, I implemented a new way for Software to be developed at my company. The idea I pitched, and which was subsequently adopted, was to extend our existing functional specification process, and add a Technical Specification section. Not really a “eureka” in the annals of Software Development, but for a company that’s been neglecting this piece of the puzzle for 25+ years, it came to some as a shock. First, some history:

The Dark Ages:
In the very early days of my company, programming requests were submitted in a Programming Enhancement Request Form, or PERF. The PERF had exactly enough information in it to bill the customer properly. The worst part (for developers) was that it had a single text area for the Description – what was supposed to be done. My company mythology says that PERFs used to be kept on paper, but nobody really believes that.

After the PERF, we started on something called the Product Design Document, or PDD. This is what most other companies in the world call Functional Specifications. This document accompanies any “large” project that we’re going to tackle. Its author is typically a member of our Customer Service department, and before it is submitted for a programming estimate, a member of our Product Development staff reviews it. Its various sections include:
Business Requirements – This section includes the “what and why” for the project. In other words, the purpose of the request as well as what benefits will be derived from the work.
Assumptions and Limitations – This lists our scope limits. For example if the request is for a new report, this section may note that the data that’s being reported is assumed to already be on the system.
Sample Outcomes – Sample of report, or they way a particular calculation should work

Just the implementation of the above saved my company hundreds of person-hours per year! It made everyone aware of what we were doing, and what was expected. Instead of just a description in a PERF, now the developer actually knew what was supposed to happen when his/her work was done! Our testing staff now had something to compare the program’s results to, rather that trying to test in a vacuum. Our Documentation Specialists had something to refer to for their process overviews.

For a while it seemed that we had found the utopia where all things worked as well as they could. Knowing that this could not be the case, I started studying what was happening once the PDDs landed on my desk.

As the supervisor, it’s my responsibility to assign the work to a developer. Once I was familiar with the PDD, I then needed to judge who on my staff was able to accomplish the task. I have programmers of several levels of knowledge and competency, as do most organizations, and finding an exact fit wasn’t always easy. I certainly didn’t want my most talented programmer working on something that someone else could do, nor did I want a relative newcomer to be tasked with something that would shatter their feeble-little fresh-out-of-college minds.

Once it was assigned to a programmer, I kept a watchful eye – remember I’m trying to make things better. I found that more often that not, the programmer would read over the PDD, and then schedule the author for a meeting to discuss the specifics. Not a problem – I’d rather them get it right the first time, rather than have to re-code. Then, almost 90% of the time, regardless of the programmer, they would schedule me to discuss how they should accomplish the task. Again, not a problem because I want them to get it right the first time. So I would set them on the path of righteousness, and be done with it.

Then something very interesting happened. A programmer came into my office and told me that we (meaning me) had made an error in the direction the programmer was taking. As it turns out, my directions put him square in the middle of Lebanon, Kansas, and they needed to be in New York City. The problem, of course, was that I and everybody else at my company were “Designing on the Fly.” Lots and lots of problems can occur by doing this, the biggest of which will become evident as I describe the new philosophy of our Specifications.

Last year, I pitched an idea to the rest of the Managers in my department, as well as the VP. This idea was to add Technical Specifications to our existing Functional Specifications. The two major sections that were added are a section for Design Overview, and Flowcharts.

The Design Overview section is now something that is completed by a high-level programmer BEFORE the request is even given an hour estimate. This is the 10,000 foot view of what needs to be changed or added. All programs, screens, tables, or parameters are listed here. The basic idea is that someone who has a good understanding of the process is deciding right there what will need to be changed. They are also in a position to give he best estimate since they know the process best.

The Flowcharts section is just that. It’s either a flowchart in the traditional sense, or a UML document, etc. Again, the senior resource for that software does all the design BEFORE it gets coded. He does this from start to finish, and here’s the best part. If he takes a path that turns out to be wrong, NO CODING HAS TO BE RECYCLED. All he has to do is change his specifications. We’ve all been in a situation where we’ve coded a huge method only to find out that we forgot one little piece of information that changes the whole design. Do we then trash the method and start over or do we work with what we have. Come on, let’s be honest, by this time, we’re either married to the code we’ve written, or we consider it one of our offspring. But it’s EASY to change a design document. We’ve got no emotional attachment to a flowchart – that’s crazy talk.

Once the technical design is complete, the project comes to me for assignment. The hope of the technical design is that once it’s done, any programmer, regardless of product knowledge, can accomplish the task.

Now life is worth living.

posted by Ken  # 9:51 AM (0) comments

Wednesday, March 03, 2004

Resume – to give you background on me 

I am a Software Development Manager for a company that specializes in benefits administration for single and multi-employer benefit plans. I have been a developer for 13 years, and have managed a team for the last 5.

I was educated at Towson State University in Baltimore, Maryland, and double-majored in Applied Mathematics and Computer Science.

I was raised an Army Brat – meaning that until I went to college, I moved every three years of my life. I’ve lived in Okinawa, Japan, Kaiserslautern, Germany, and Alabama, Arizona, Georgia, Virginia, Washington, DC, and Maryland in the US.

I do all of my best work in Java, for which I am a SCJP. My company uses a non-1NF database, and with it a language called UniBasic, so I have expertise in these too, although I try to avoid working with this language.

I plan on using this blog to write about what happens in my department, and company from time to time. I will write about the outcomes of the various decisions that my colleagues and I make.

My hope for this little project is two fold: 1) to make me a better manager; and 2) to make me a better writer

I can always be emailed at mkclark9@yahoo.com. So that I can filter these emails out, please put “Your Blog” in the subject. The only thing I want to keep private is the company where I work – thus the yahoo address.

posted by Ken  # 9:18 AM (0) comments


03/01/2004 - 04/01/2004   04/01/2004 - 05/01/2004   07/01/2004 - 08/01/2004  

This page is powered by Blogger. Isn't yours?