The importance of an creating an overarching technical plan at the beginning of a project is often debated. Based on past experience, it isn't always created at the outset of a project, if at all. Sometimes seen as a barrier to just getting things done, other times relegated to Semantics Hell (a useful delaying tactic), the technical specification is an often misunderstood document. At its core, it provides a central document for all stakeholders to reference which details the project’s design and functionality, helps the project avoid scope creep, and keeps all parties on task and on budget.
A Spec by Any Other Name...
...should still get the job done. Semantics often rears its ugly head in the tech spec debate, so we should establish some common ground before moving forward. Is it really a "technical" spec? Or is it really a "functional" spec? The latter often refers to a document created from a user point-of-view: the widget's various features, how they work, and the user interface. The former is from a technical point-of-view: how those features will be implemented, what technologies will be used, and the like.
For Metal Toad's purposes, the technical specification is a mix of the two; all of the functionality is detailed from the user's perspective with specific technologies (e.g. Drupal modules) called out as appropriate. For the rest of this post, I'll refer to the document as the "tech spec" or simply "the spec".
In the end, it doesn't matter what we call it as long as it's created, but we still haven't addressed the "Whys" of the spec. Perhaps the most important reason to create the tech spec is just to design the thing.
See First That the Tech Spec Design Is Wise and Just
The main reason anyone would create a tech spec is simply to design the project. Even when working alone, investing the time to solidify all the ideas and structure planning in writing at the front end of a project will save time and possible headaches later when the project is well on its way. What are the main elements? Where are they located? When clicking on that widget or this banner, what happens? Is there a backend, and if so, how does it work?
Of course, the design phase will likely be a collaborative affair. Developers will contribute their ideas and sanity-check the tech, and if you are developing the project for a client other than yourself, they should have significant input into the doc. The project manager or business analyst will then be the party responsible for pulling it all together in a form that makes sense to everyone.
All the Tech Spec's a Stage...
...and everyone on the team should have access to it. After the spec is finalized and approved by the client, it serves as the go-to document for all involved, aligning expectations for every aspect of the project and beyond. Following the DRY (Don't Repeat Yourself) principle, the tech spec allows you to communicate everything to all stakeholders once.
Besides the clients, developers, and project managers, marketers can use it to start plans for the launch campaign, QA can create test plans, and sales can leverage details to impress and land new clients -- all from a single document. Beyond communicating the details of the project and keeping everyone in sync, the tech spec has the added benefit of ensuring the scope of the project does not venture out from its initially-agreed upon proportions.
...Pursue the Tech Spec Resolutely
Scope creep. Nearly everyone involved in any kind of project anywhere (from software to house remodeling) has experienced it. For the lucky uninitiated, scope or feature creep refers to the incremental, subtle (sometimes not-so-subtle) changes or line item additions introduced after its launch by someone on the project, oftentimes the client. Although the tech spec isn't necessarily scope creep's kryptonite, with the right team and processes in place, creep can be managed, if not largely alleviated. Because the tech spec details all of the features and functionality agreed upon at the outset, a good project manager can point to the document as a reminder of what is being developed to keep the project on track.
Of course, the tech spec isn't an inflexible document; there can be some negotiated changes, but it must have sign-off from both parties with adjusted timelines and budgets, if necessary. At Metal Toad, we normally keep a running wishlist of these last-minute features and revisit this list towards the end of the project. Working in concert with the client, we can prioritize the list, and if extra development hours are available, we will move forward accordingly. If there are no extra hours, it is an opportunity to move the work to a new phase (and a new contract), ensuring the original project stays on time and on budget.
Be Not Afraid of Greatness... or the Tech Spec
I've been in the software industry off-and-on now for almost a decade, and other than a few personal projects, this is the first time I've actually worked with technical specifications. In hindsight, I see that the lack of a spec was probably the single greatest contributing factor to many-a-failed project. Luckily, Metal Toad creates one for nearly every project we take on, and their importance is borne out by our track record of successful projects.
The tech spec may not be right for you if your project is tiny, but chances are, you really do need one. So why not just do it? Leave your comments below. And for further reading on the joys and wherefores of creating specifications, Joel Spolsky, co-founder of Stack Overflow and Fog Creek Software, wrote a series in 2000 about the subject that still resonates over a decade later.