What is a functional spec?

Folder stack by Christine Balderas @ iStockphoto

It has many names. It’s brought up joy and relief to some people. It’s brought down pain and agony to some people. Some say it created order from chaos. Some say it restricted their freedom to express, to create and to change.

It is the functional spec. Also known as the design specification or technical specification, it is simply a document or cluster of documents detailing the workings of a software project.

I use the term “software project” instead of “software application” because the functional spec is to describe what interactions are available between people and computer (broadly speaking). It just so happens that an application (usually custom written) sits between them most of the time. Rather than further defining it in abstract ideas, let me show you 3 examples.

The spoon-feed

It was the first time I had anyone reporting to me. Well not exactly reporting to me. I’m supposed to write up a spec, defining tasks in it, and hand it over to someone stationed in China. I would then liaise with that Chinese developer, doing code reviews, giving guidance and finally grading the fella.

Offshoring is all the rage, and despite the polite feedback about how difficult the situation was, I had to work with this arrangement. Let me list a few reasons why it’s a little hard to get the project going smoothly.

  • They’re fresh graduates
  • They know zero about our (specific) business
  • They’re Chinese (let me explain a little further down before hammering me, ok?)
  • Long distance communication
  • Working times

From my observations and my own experience, I can tell you that sometimes it’s hard to move from an academic realm into the professional realm. There might be tons more code, with massive behemoths of libraries and documentation. Practicality sometimes win over theory, creating seemingly incorrect code, compounded by comments far and few in between.

They also know nothing about the existing software and business we support. Either explain to them in detail so they can understand the business requirements, or cut out enough of the business stuff so only coding stuff is left. Which is usually the case.

I’m a Chinese. I’m fairly proficient with conversational speech in Chinese. Yet I falter repeatedly, trying to communicate to them because I understand code in English. They understand code better in Chinese! Suddenly, explaining concepts and business logic became a lot harder, because I don’t know enough Chinese to translate smoothly, and they aren’t fluent enough in English to get it.

And they are far. I’m in Singapore and they’re in China. Big deal that we’re in the same time zone. If you are in the right spot, the North pole and Antarctica are also in the same time zone. Some things are just better explained in person, with facial expressions, with gestures, with voice intonations. Video conferencing is an activity left for higher management. I’m to settle for email, maybe a phone call and live screen presentations in virtual meetings.

With the person sitting next to me, I can just point at the button on the screen and say “just move this to here”, pointing to a new position. Long distance, I have to do screen shots and I have to describe in exact detail where I want that button to go.

I don’t even know what time they start work, when they go for lunch, what time they leave work. I don’t know whether they are in meetings with their (real) direct supervisors, or undergoing training. In part, maybe because of their very recent departure from the academic environment, they haven’t inculcated a willingness to complete the work, even if it means they stay back a little. Of course, if the only transport out of their workplace leaves at a certain time, they’d have to go…

Ok, I nearly lost the line of thought about where I’m going with this. With all the reasons stated above, the functional specs I sent to them were very detailed and practically devoid of business logic. They don’t need to know, they don’t want to know, and quite frankly, it doesn’t matter whether they know or not.

My colleagues have done specs and assigned tasks to the offshore developers too. My impression was that my colleagues had been exceedingly detailed in their descriptions. The Word and Excel documents were so filled with pseudo code, that all that’s really missing is the feature to compile an executable straight out from Microsoft Office itself.

Most of the ASP.NET tasks simply degraded into copy and paste operations from the part of the developers. A textbox is supposed to hold a database field of char(10). The least they could do was to actually validate that at most 10 characters were given, right? You mean, I have to explicitly tell them that? If I had to spoon-feed everything to them, what would they learn?

The drowner

It happens in big teams. Someone’s got to do documentation, and they have the people to do it. The business people churn out all sorts of documents. The testers churn out all sorts of test scenarios and test data. And the programmers were then expected to churn out a matching amount of documents, preferably replete with screen shots, enough technical details to wow (but not woe) them, and lots and lots of calculations to show how their business logic turns imaginary scenarios into profits.

I knew of this person who documented exactly what a particular button would do, right down to which tables were used. I knew of another person who had to document the enterprise framework he created so other developers knew how to use his custom controls. It was downright stifling. My intuitive sense told me there was a better way to move the project along. The rules and documentation were bogging the project down.

In another project, the business users were just a bit enthusiastic. Documents seemingly come into existence with each breath taken. They weren’t satisfied with a development environment, a test environment and a production environment. They needed five.

Test scenarios and data weren’t just necessary; they’d positively die without it. There were Excel spreadsheets with neat little tiny almost-imperceptible text describing the exact condition a test was to be conducted, with frozen column panels, columns to checked (with a tick character, if you can find it), and a “remarks” column (always handy).

If you thought truth tables were bad, you are in for a rude awakening. Business logic frequently run with multiple conditions. Say there’s a “number greater 30 and item code is ABC”. What if the number is 25 and the item code is XYZ? Oh goodness gracious, I didn’t think of that! The number is implied to be positive? What happens if it’s negative? Better include that case.

And they want a technically verbose version too. It doesn’t matter if they couldn’t quite understand it. They just want it, in case you’re gone, and they pass it to the next programmer.

The gist

The “gist” works best in a small tightly knit team with highly specialised skills and knowledge. It provides enough details so business people can coincide it with their understanding. It provides enough clues for testers to work out test scenarios. And it provides just enough information for a programmer to start.

There’s enough information to start thinking about design, yet not confined to any strict layout. Enough to run through coding logic based on business logic, discovering missing implications previously unbeknownst. Enough freedom to still change underlying code while providing a consistent frontal interface.

The gist also comes about because it’s a small tightly knit team. There’s simply not enough people and time to create a comprehensive document. We’re programmers, the intelligent people, right? So we fill in more blanks than other people. Hence, when done properly, we don’t need as much words in a document. Code can express our meanings much more effectively.

That said, every team member must be fairly knowledgeable in a broad range of topics. Since there are less people, members’ knowledge then bleed into each other. When documentation is scarce, the ability to fill in blanks becomes extremely important. Each member just happens to do a certain portion of the project, and do it well.

So what is it really?

I honestly can’t tell you that. Just write and use functional specifications in the best manner for your particular situation. I favour the flexibility and freedom to make code changes when required. An iron-clad documentation of rules will impede rapid progress.

Besides, the only way to have a completed application is to finish writing the application. The application might look and behave totally different from what was originally envisioned. Newton’s law at work; it’s very hard to undo mountains of paperwork.