Functional Specifications

Is documentation a blessing or a curse? If you’re working on an agile project does it get in the way? If you’re updating a core system that runs your company’s business, are you cursing the analyst who didn’t adequately document all the business functionality? Is today’s agile project tomorrow’s core system?

A user of almost any given software system or business application will require precise analytics in order to objectively measure its effectiveness, or the effectiveness of an associated product. These analytics –or reports—therefore, must measure the right criteria at the right time(s) in the right way in order to be useful to the user. For that reason, any newly proposed reporting function requires careful, measured, thoughtful and thoroughly vetted requirements in order to ensure its efficacy.

Business analysis is an important aspect of agile software development projects, but the agile approach is significantly different than the traditional, serial approach of yesteryear. Because the agile approach to business analysis is different the approach to requirements specification is also different, for many traditionalists this will prove to be a significant cultural shock to them at first. In this article I briefly overview how business analysis activities fit into an agile approach, question some of the dogma around documentation within the traditional community, summarize some of the evidence showing that agile approaches are more effective in practice than traditional approaches, and end with strategies for specifying requirements on an agile project.

Ideally, an agile document is just barely good enough, or just barely sufficient, for the situation at hand. Documentation is an important part of agile software development projects, but unlike traditionalists who often see documentation as a risk reduction strategy, agilists typically see documentation as a strategy which increases overall project risk and therefore strive to be as efficient as possible when it comes to documentation. Agilists write documentation when that's the best way to achieve the relevant goals, but there often proves to be better ways to achieve those goals than writing static documentation. This article summarizes common "best practices" which agilists have adopted with respect to documentation.

THE ANALYST (aka, Systems Analyst, Systems Engineer, Systems Architect, Business Analyst) - requires specifications about the end-User's information requirements in order to design a system solution.  This is normally based on a definition of the user's business actions and/or decisions to be supported.  Following the system design, the Analyst produces the specifications required by the Programmer and DBA to fulfill their part of the puzzle.  From this perspective, the Analyst is the translator between the end-User and the Programmers and DBAs.

Each party has his own unique perspective of the puzzle and, as such, requires different "specifications."  To compound the problem though, the role of the Analyst sharply diminished over the years, leaving it to the Programmers to try and determine what the end-User needs, a skill they are typically not trained or suited for. 

What Is A Functional Specification? Functional specifications (functional specs), in the end, are the blueprint for how you want a particular web project or application to look and work. It details what the finished product will do, how a user will interact with it, and what it will look like. By creating a blueprint of the product first, time an...

A multitude of sins can be hidden behind the phrase “living document.” You can submit documents that are incomplete or inconsistent as long as you promise to fix it later. In this month’s issue of Strategic Software Engineering, I want to talk about the strategic importance of being realistic about the state of knowledge, plans an...

Every project has requirements. It doesn't matter if it's building hardware solutions, developing software solutions, installing networks, protecting data, or training users. For the project to be a success, knowing what the requirements are is an absolute must. Requirements exist for virtually any components of a project or task. For example, a p...

 Most books and articles on software requirements are written as though you’re gathering requirements for a brand-new product—what’s sometimes called a green-field project. In reality, few people have that opportunity on every project. Many developers work on maintenance projects. In such a project you’re usually adding...

A use case represents a case of use of a system, ideally one that captures a functional requirement in terms of an identifiable and testable goal. So, what is the best way to document a use case? Approaches to content range from diagrammatic to textual, formal to free form, expansive and detailed to brief and abstract. The approaches to tool usage ...

In this fourth and final part of the series I'll share some of my advice for writing good specs. The biggest complaint you'll hear from teams that do write specs is that "nobody reads them." When nobody reads specs, the people who write them tend to get a little bit cynical. It's like the old Dilbert cartoon in which engineers use stacks of 4-inc...

Now that you've read all about why you need a spec and what a spec has in it, let's talk about who should write them. Who writes specs? Let me give you a little Microsoft history here. When Microsoft started growing seriously in the 1980s, everybody there had read The Mythical Man-Month, one of the classics of software management. (If you haven'...

This series of articles is about functional specifications, not technical specifications. People get these mixed up. I don't know if there's any standard terminology, but here's what I mean when I use these terms. A functional specification describes how a product will work entirely from the user's perspective. It doesn't care how the thing is i...

It seems that specs are like flossing: everybody knows they should be writing them, but nobody does. Why won't people write specs? People claim that it's because they're saving time by skipping the spec-writing phase. They act as if spec-writing was a luxury reserved for NASA space shuttle engineers, or people who work for giant, established insu...

Beware of the colleague or supplier who spends large amounts of time in meetings discussing the format, sequence, and wording of documents they will deliver and very little time on the actual content. Strategically, substance is what counts. In this issue of Strategic Software Engineering I will point to some common problems when form becomes a hig...