You are working on a product which has shipped prior versions, or at least has been in development for a few months, and you are part of an engineering team which has one or more program managers, a few developers, and a few testers. The planning effort has identified a number of requirements that the product must meet. A program managers is assigned to design the functionality of a feature that would satisfy a key requirement in a way that is coherent with the entire product. As the program manager is starting the work on the functional specification, you are assigned as the developer for that feature. Your first deliverable is the software design specification for the feature – or the design spec in short.
Yes, you heard right. A design specification. This one is the kind of teams that uses specs, and design specs in particular. And you will have to create one for your feature.
But what is a design spec?
Before we get to the details, let’s put the design spec in the right context. In order to deliver a software product that is usable and useful to its customers in a planned and predictable manner (as opposed to “let’s build it and see if they like it”), four types of information are needed – a description of the business requirements or needs, a description of how these requirements will map to a set of features and how the features will work from the perspective of the customer, a description of how these features will be implemented and the work list breakdown for implementing them, and finally, a description of how the implementation will be validated. For very simple projects, these four types of descriptions could take just a few pages in one document. For most non-trivial software projects, however, each of these descriptions would typically warrant a separate document – which are commonly referred to as the requirements spec, the functional spec, the design spec, and the test spec.
The requirements spec lists the business requirements and needs customers have. It does not specify what features will be implemented in order to satisfy those requirements. For example, the requirements for a weather web site could be to provide the user with information on the current weather and the 3-day forecast for one or more locations of choice, and the list of browsers on which the web site needs to work.
The functional spec describes the features that will be implemented, how they work in end-to-end scenarios, and how they meet the requirements, without specifying how these features will be implemented. For our simple weather web site, the functional spec would normally provide a list of scenarios screen mockups for the web site, with details such as “In order to change the temperature display from Fahrenheit to Celsius, the user needs to click the Settings link, then click …”.
The design spec describes the details for how the features and end-to-end scenarios from the functional spec will be implemented. In our example, the spec would typically describe the details of a service running in the cloud and the types of requests it handles (such as GetTemperatureForLocation), how the front-end UI will be structured, how it will communicate with the service, and other design decisions. Last but not least, it lists the work items breakdown needed to implement the work, with reasonable cost estimates.
Finally, the test spec lists the test strategies, test automation, test cases, configurations, manual testing, and any other activities required to confirm that the features are implemented in a way that satisfies the initial requirements as well as the features and end-to-end scenarios designed in the functional spec, and, even more importantly, that the product works, that it works well, and that it works the way that customers would want it to work.
Again, what is a design spec?
I apologize for any inconvenience the above detour may have caused, but it was important to put things in context. The design spec does not invent requirements, features, user interactions, or scenarios. The design spec is fundamentally a technical document and as such it needs those detailed requirements and scenarios to exist. If they do, it is the job of the design spec to describe in details how to implement the feature designed in the functional spec in a way that is coherent with the rest of the system being developed.
At a high level, the design spec is a document that should provide the following:
- Summary – a brief overview of the requirements, scope of work, proposed solution, and anything else the target audience would want to learn upfront about this work. Typically the summary would be between one or two sentences to a half page.
- Cross links to the other specs – since the design spec uses the functional spec as input, and is an input for the test spec, cross-referencing the specs makes it easy to make sure that all the documents and their owners remain in sync.
- Scope of the work – a list of the scenarios, functionality, and behaviors from the functional spec which will be enabled, and (often times more importantly) the ones that will not be enabled.
- Design overview – a high-level description of the proposed design and its relationships with the existing architecture of the product. One or a few component diagrams clearly indicating the existing and the proposed new work and how they interact at a high level are typically expected.
- Detailed design – usually the meat of the design spec, this section should include sufficient details on implementing the components of the solution such that a developer without prior knowledge of this feature can implement it truthfully or support it without significant additional research, prototyping, or re-design. Various teams may have different expectations for the level of details required in design specs, but as a rule of thumb, the level of details should be adequate to allow the work items costs (below) to be estimated at the granularity required by the software methodology the team is using. Various types of diagrams may be applicable and useful.
- Additional details – usually the other substantial portion of the spec, this will include any further notes relevant to the design or implementation details that would be useful to a future developer or tester working on the feature. For example justifications for key design decisions, considered and rejected solutions, notes to the tester, risks, glossary of terms, links to other relevant documents, revision history, and more.
- Work items – a breakdown of all the work items needed to complete the proposed solution with reasonable cost estimations. I share the opinion that work items should have estimated costs between a half day and 2-3 days at the most. Any work item estimated at more than 3 days is most likely not understood sufficiently clearly, and needs to be broken down into several items.
- Open issues – a list of issues or questions which needs to be investigated further and which could have a non-trivial impact on the product, the name of the person who will figure out the details, and an ETA for resolving the issue.
So how do I write one?
I’ll reserve this topic for another post, but in summary, don’t think about writing a document. Rather, start with the goal of figuring out what the design needs to be, what choices you need to make, and what details you need to understand. Research, prototype, design, estimate and iterate as needed. As you do that work, keep recording the findings and open questions in a document. This document is the design spec.
Or, in case you prefer to start off from a spec template, here is a short 2-page MS Word Design spec template based on the above description. Enjoy.