Consider the following nightmares.
You’re about to launch a new feature your team has spent weeks on. When you try to verify in staging, nothing works as expected. After digging into the problem, you discover that your feature relies on a service that another team recently deprecated.
While trying to integrate client and server work for a new feature in your app, you discover that the client engineer has been working off of an outdated tech spec, nullifying weeks of their work.
After announcing that your team is working on a new feature, you’re flooded with requests to widen the scope of the project. Bogged down by new requirements, you begin to wonder whether the feature will ever make it into production.
What do these nightmare scenarios have in common? Each could have been prevented by an awesome tech spec: a document, usually written by an engineer, that describes how a feature, project, or service will work from a technical perspective.
The very idea of a tech spec can seem contrary to the Silicon Valley ethos. Move fast — break things — rapidly iterate — be a doer. Why spend time writing, disseminating, and updating a tech spec when that time could be spent actually building the damn thing?
But tech specs have more utility than most engineers realize. A thoughtful, well-written tech spec unlocks many benefits, such as:
(Almost) Bug-Free Releases
A thorough tech spec exposes broad ideas (and often low-level implementation details like endpoint names and error codes) to a wide audience, maximizing the chance that a bug or regression will be caught sooner rather than later. There are always unexpected bugs, but a good tech spec can eliminate the vast majority by getting many sets of eyes on your proposal.
Documentation
Your tech spec serves as documentation both during feature implementation and after feature launch. During feature implementation, it specifies exactly what work needs to be done. After launch, it helps uninformed engineers get up to speed quickly on the inner workings of a feature and the tradeoffs involved.
Of course, documentation is only as useful as it is accessible. At Lyft we have a collection of tech specs — that any engineer can view and contribute to — organized under a mailing list. Many engineers use it to solicit feedback, raise awareness of new projects, and collaborate across teams. Others use the collection to better understand existing features and services. Its high visibility and transparency allows even the most junior engineers to build with confidence.
Fast Iteration
Reaching consensus on feature design and implementation in the tech spec stage means less contention down the road — invaluable when you’re under a crunch, trying to get a feature launched. After launch, the tech spec serves as a valuable reference guide where stakeholders can quickly locate accurate information — like why certain implementation decisions were made, what the project scope is, and how it integrates with other platforms and services.
After reading this guide, you’ll be equipped to author fully-realized tech specs that take your features and team to the next level. You’ll thank us later!
Before You Write — Give Your Tech Spec a Purpose
The Pareto Principle — that only 20% of input generally results in 80% of output — quantifies what most people intuitively understand: some uses of time are more efficient than others. The same rule applies to writing tech specs. Spending your time and effort wisely will pay outsized dividends later. A well thought out tech spec is a tool that works on your behalf, making your job easier and your feature better. It has a purpose — improving intra-team communication, for example, or anticipating and addressing stakeholder concerns. A tech spec without a purpose? It’s a waste of time.
To maximize the utility of your tech spec, define its purpose before you start writing. Ask yourself, “What do I hope to achieve through this tech spec?” Making this decision beforehand streamlines the writing process and ensures the spec will have value to its readers (and, therefore, to you). Your answer will be the foundation of your tech spec, determining attributes like technical detail. This grid lays out several common purposes for tech specs, and how those purposes are reflected in the final tech spec:
As your project and purpose changes, your spec will too. The early stages of a project may call for a high-level spec designed to get buy-in from stakeholders. After buy-in is achieved, you might transition your spec to a lower-level document that outlines all the engineering work needed to complete the project, including specific APIs, errors, and analytics.
Writing the Tech Spec — Key Sections
Although every tech spec looks different, starting from a template allows you to take advantage of known best practices. Here we’ll introduce a loose template for tech specs by walking through the spec for a hypothetical project called Spot the Bot — a Twitter bot that will tweet cute pictures of puppies.
Here’s what the header section for a Spot the Bot tech spec would look like at Lyft:
If applicable — e.g., for frontend or client work — add a primary mock or screenshot at the top of document so readers can get an intuitive, visual sense of the project.
Summary
This is your tech spec’s abstract: the who/what/when/where/why of your entire proposal, made succinct.
Spot the bot is a twitter bot that tweets pictures of dogs at predefined chronological intervals. The dog images are retrieved via a GET call to Dog API.
Background
Contextualize your project: why build it? What is the motivation? What user problems are you attempting to solve? What previous efforts, if any, have been made to solve this problem?
We are looking to expand our brand imprint within the millennial segment. Spot the Bot will target the millennial audience by providing instant access to high-quality, curated dog pictures. We will differentiate ourselves from the competition by delivering higher-quality pictures.
Goals
Highlight all the outcomes that you predict will result from your work, both purposeful and inadvertent. This is especially important when contributing to a large ecosystem of services and code. This section, along with the Measurable Impact section, are the yardstick by which you’ll evaluate the success of your project: “Did we achieve our intended goals and impact?”
- Disrupt monotonous Twitter feeds with fun, unexpected, and “on-brand” images. (subjective)
- Introduce millennial users to our brand with relevant and engaging content. (subjective)
- Integrate with Twitter (to automate tweeting) and Dog API (to pull puppy photo content) (objective)
Non-Goals
The concept of a “non-goal” can be unintuitive and confusing. Here’s how it’s defined by Lyft’s internal tech spec guide: “A non-goal is something you are intentionally not doing or solving with your project, even if it could be related. Defining non-goals helps limit the scope of your project and prevents feature creep.” Just like goals, non-goals should be eminently readable (we suggest bullet points) so they immediately jump out to reviewers. Burying your non-goals deep in your tech spec virtually ensures that a casual reader will try to widen your project’s scope.
- Disseminating dog pictures via another platform (i.e. facebook, instagram)
- Creating or hosting an in-house dog photo database (we will instead take a dependency on Dog API)
- Configurable “post times” — in v1, dog photos will be posted at a hardcoded chronological interval.
Plan
This will be the longest part of your tech spec; it is the product of most of your research and preparation. In this section, you’ll describe your engineering approach. If you haven’t decided on a single course of action to accomplish your project, list the approaches you’re considering; this will enable your reviewers to help you choose. Your level of detail will depend on your tech spec’s purpose and your intended audience. Make it descriptive enough to encourage productive suggestions!
This is also a good place to include illustrations that show how your project interacts with existing systems. This may mean a flow chart representing the user experience…or a diagram showing data flow through different services and databases.
If your tech spec covers low-level topics, consider including HTTP response codes, JSON request/response snippets, and error names.
Measuring Impact
This section defines specific metrics that you expect your project will impact; they should map directly to your goals. At Lyft, engineers collaborate with data scientists and product managers to define these metrics; we are fortunate to have robust data pipelines and analytical tools to facilitate this process. In the early stages of a project, these metrics can help answer difficult questions around prioritization (“Given our finite engineering resources, which feature is more important to build?”). After launch, they become means of gauging the project’s success and identifying areas for improvement.
- Reach 2K twitter followers within 2 months of launch via cross-account and cross-platform promotion.
- At least 50% followers are non-bots; at least 20% are age 18–35
Security, Privacy, Risks
If the project is external-facing, list the ways in which malicious users could exploit your change. Highlighting the risks of your project can be anxiety-inducing; what if reviewers criticize you for introducing all this risk to the system/product? Still, it’s important to solicit these critiques so that reviewers can pose questions and solutions that will ultimately make your feature more robust.
Other Considerations
Discuss approaches you considered (but ultimately decided against). This serves as a form of documentation and can also preempt suggestions from reviewers to investigate approaches you’ve already discarded.
Spot the Bot Email Bot: emails instead of tweets. Decided not to implement because it doesn’t scale well, and user demand is low.
Milestones
To keep your project on track, divide all work into key accomplishments and assign estimated dates.
- Dog API integration complete: October 14th
- Post interval configurable: October 17th
- QA complete: October 21st
Make this section a source of truth — if a milestone is pushed back, note it here. Keeping milestones up-to-date can prevent misunderstandings about the project’s status and help ensure that the project ships in a reasonable time frame. This is especially useful for larger teams and organizations.
Open Questions
List unresolved design or implementation questions, along with an invitation for reviewers to give feedback. Feel free to call out specific people who may have valuable input.
We’ll start by tweeting once ever hour, on the hour. Can someone on Data Analytics confirm that this rate will maximize our audience?
Getting Feedback
Distributing Your Tech Spec
Polished tech specs are more likely to get timely, thorough, and useful feedback from reviewers. To that end, it’s a good idea to ask a teammate for an initial review before distributing your tech spec widely — they can catch any glaring errors or omissions. Then send your tech spec to wider audiences: first your team, then a stakeholder, and finally all interested parties. With each round, your spec becomes more refined (and more appealing to reviewers).
Engaging with Feedback
Most comments warrant a response, so be sure they have one, whether from you or another reader. When an issue is resolved, note its resolution explicitly in the comments or in the tech spec itself. Engage with your readers and reviewers; they want to help you build the best possible product!
If you find yourself at a point where comments are no longer helpful, it may be time to close your tech spec to feedback in order to reach a version of the spec that you can start to build on or ticket up. Any non-critical feedback after this point can be incorporated into a v2.
A tech spec is a living document, and it’s important for the reader’s sake — and for yours — that you date every major change you make. This allows readers to quickly assess your tech spec’s relevance and identify changes.
We hope this has convinced you to join the minority (but soon to be majority) of folks who invest time into crafting good tech specs. Why? Because tech specs are an upfront investment of time and effort that in the long run can create exponential payoffs for you and your team. Use them well.
This post was written by two software engineers at Lyft, @blackqueentech and @chloerevery. We encourage you to contact us with questions or feedback in the comments. Like what you’ve heard? Join our team and help build the future of transportation!
