Design Document

A software design description (a.k.a. software design document or SDD) is a written description of a software product, that a software designer writes in order to give a software development team overall guidance to the architecture of the software project. An SDD usually accompanies an architecture diagram with pointers to detailed feature specifications of smaller pieces of the design. Practically, the description is required to coordinate a large team under a single vision, needs to be a stable reference, and outline all parts of the software and how they will work.

The Software Specification Design Documents

So, when you take on a new project, before you even open Xcode or Visual Studio, you need to have clear and agreed-upon design goals. And these goals should be established in a specification document. If the client hasn’t written one, you should write it, and submit it to them for review before you even open your IDE. And if you encounter a client who says, “We don’t have time for design documents”, candidly, you should walk away from the project because you have trouble ahead. The specification need not be particularly lengthy; it can be just a few pages, but at the very least it should lay out the user interface, include wireframes (if there’s a UI component), and set completion milestones.

Without this document, you’ll end up in a loop of acrimonious equivocation, clients disputing what they told you or what you told them, angrily sending cut-and-pastes of previous communications, interpreting and arguing until the time comes when the client demands that you make changes to bring the application into conformance with “what they actually asked for,” and expects you to make those changes without pay.

With this software design document, you’ll have an answer to any such quibble: when disagreements arise, you can refer to the specification which the client agreed to and signed-off on, pointing out that you have fulfilled it to the letter. Instead of angry arguments, you’ll make amendments and clarifications to the document. If anything, the client will apologize for letting the imprecision slip through in the first place.

We all want satisfied clients. We all want a friendly working relationship. And we all want the pride of a job well-done. But these can’t be achieved if there’s any vagueness whatsoever about what the job actually is. If your client says that a design document is too much extra work, it’s your job to explain to them that the realextra work will emerge when revisions need to be made due to some sort of misunderstanding. If the client still insists that you advance without such a document, you should accept the fact that you have an unworkable relationship and walk away.

What should the software specification… specify?

At the very least, it should be a description of the desired application, criteria for completion, and milestones. Remember, you are sharing what is best described as a requirements and function document, not an implementation specification. And unless a specific implementation is a stated client objective, how you make it work is up to you.

User Interface

Most projects are applications, not libraries or frameworks. But if you happen to have one of these as a deliverable, count yourself lucky because the user interface is far and away the most problematic component of your design document template, and almost always leads to misunderstandings. Many clients will send you perfect illustrations created in a graphic editor by a graphic designer who is not a programmer. But the problem is: these illustrations say nothing about animations, control states (e.g., Is this button disabled? Does it disappear when unusable?), or even what actions to perform when a button is pressed.

Many clients will send you perfect illustrations created in a graphic editor by a graphic designer who is not a programmer. But these illustrations say nothing about animations, control states, or even what actions to perform when a button is pressed.

Before you start writing the code behind these illustrations, you should be able to answer all of those questions. Specifically, you should know:

1. Are controls always visible and/or enabled? Under what conditions do their states change?
2. Looks like a bitmap—is it a button?
3. What transitions occur between these states and views? And how should they be animated?

If it’s up to you to generate the UI for the client’s concurrence, do the same in reverse: use a wireframe tool and create a complete set of screen layouts, including any variants that the views show in different application states. This can be exhaustive and tedious work, but you won’t regret it—it can save you from re-writing huge amounts of code and re-creating interfaces due to a minor misunderstanding with major implications. If you’re creating a dual application (e.g., for both iPhone and iPad), create separate wireframes for both.

Screen dimensions are important too. There are (as of writing) three sizes of iPhone screens. Separate wireframes for 3.5” and 4” screens are probably excessive, but you may have to make them; in most cases, you can simply change proportions.

If your client supplies you with graphics, make sure that they are correctly sized with the proper aspect ratios; morphing any bitmap that has text or objects (like circles) will introduce distortions. If they don’t match, tell the client to re-create them with matching sizes. Don’t presume that you can stretch a 3.5” splash screen into a 4” splash and just roll with it.

Functionality

Key questions to ask in the application design document:

• What does the application do, and how quickly does it do it?
• What are possible failure conditions and how are they handled?
• What one-time operations are done at the first execution (i.e., after installation)?
• If the user creates entries of any kind (e.g., bookmarks), what are the limitations?

Generalize these ideas, and be as detailed and thorough as you can—because errors or misunderstandings here will mean rewriting code.

Milestones

Your specification template should layout clear milestones. If your client writes the functional and user interface design, you should subsequently agree on a set of milestones. Sometimes these are billing thresholds as well, but at the very least they provide a clear metric toward completion. Milestones may be in terms of functionality and/or components; they may even be separate applications if the gig involves a suite of deliverables. When possible, milestones should be approximately equal in duration.