We at Mixmax are excited to introduce our second annual Engineering Blog Advent Calendar! Last year, we ushered in the holidays with twelve one per day blog posts. That went over so well, we’ve decided to make it an annual tradition!
For the next twelve days, we’ll be sharing one engineering post per day: some about our stack, some about tricky problems we’ve dealt with, and some about our philosophy and culture. We hope to be just as useful to future engineering teams as past engineering blogs have been to us. Follow @mixmax on Twitter for the latest posts, or check back here daily for an updated list. You can also Tweet the authors, linked to the right of each post, to offer your valuable feedback!
- Writing Effective Engineering Specs
- Introducing the Mixmax Sequence Picker SDK
- Handling 3rd-party JavaScript with Rollup
- Terraforming all the things
- Recruiting Engineers Using Online Challenges
- Database-backed job processing
- Precisely observing structural page changes
- Beating Spam-Detection Bots
- Introducing search-string: an advanced search string parser
- Improving Mongo performance by managing indexes
- Elasticsearch vs Redshift for Real-Time Ad-Hoc Analytics Queries
- How to work remotely
Now for the first post. Drumroll please…
Writing Effective Engineering Specs
Before Mixmax engineers start a major new project, such as recommended send times or delegated sending, there are several questions we must answer. Which users’ needs will the project serve? How will we go about implementation? How much time will the work require? To answer these questions and more, the engineer in charge of the project writes a document called an Engineering Specification (or Eng Spec for short).
A well written Eng Spec can be a phenomenally useful tool for making estimates, identifying unknowns, prioritizing, and sharing knowledge. A poorly written Eng Spec can be a confusing mess that wastes time and leads engineers into dead ends. Here are a few of the lessons we at Mixmax have learned about how to write effective Engineering Specs.
Focus on Users
At Mixmax, we don’t start a project unless we can clearly demonstrate the value it adds for our users. That value doesn’t have to be provided directly — for instance, architecture overhauls can speed up long term development velocity — but we’re mindful to not burn time on, say, over optimizing developer experience. When we began the switch from Backbone to React, we didn’t do it because React is more fun (although it is :). We did it because it offered distinct performance and user experience benefits.
We believe that Specs should always focus on real world use cases. Frequently reconsidering to these use cases while building lets us create targeted and elegant user experiences. We also try hard to split projects into incremental releases, prioritized by the value they provide to users. This lets us deliver 90% of a feature’s value in 50% of the time. A good Eng Spec enables this UX elegance and high velocity by keeping a laser focus on users.
Set SMART Goals
In keeping with our focus on users, we believe Eng Specs should include written goals that describe the value the project provides. Of course, written goals are useless if you don’t have any way of determining whether you’ve hit them. Accordingly, we make sure that all of our goals are SMART: Specific, Measurable, Assigned, Realistic, and Timeboxed.
This is a SMART goal:
- “Reduce attachment failure rate to sub-0.25% of DAUs by Thursday, Feb 11.”
These are not SMART goals:
- “Make attachments work 100% of the time”: not realistic
- “Fix attachment failure rate by Thursday Feb 11”: not measurable
- “Implement sequence folders”: not specific, measurable, or timeboxed
Because they are concrete rather than abstract, SMART goals remain useful during implementation. Having these goals written down and frequently measuring our progress against them lets us quickly understand if a project is getting off track. Even after a project is complete, SMART goals continue to be useful for retrospectives and evaluation.
Write Actual Code
We’ve found that, when writing about software, it’s often clearer and quicker to communicate in code than in English. Every engineer has a unique written and spoken communication style, but at Mixmax, Javascript is a lingua franca. Why spend hundreds of words clarifying the exact structure of a record in the database when showing some JSON would do?
At Mixmax, our Eng Specs are littered with code snippets and JSONs. Walking through common use cases step by step with example records and pseudocode can help engineers reason about problems, think about performance, and detect edge cases early. Sometimes, we even end up writing code in a spec that gets literally cut and pasted into our IDEs!
Build Estimates Incrementally
Making good estimates is important to prioritizing work and keeping a sizable engineering team humming along. Unfortunately, it’s also really hard. The enemy of a good estimate is the “unknown unknown”; the work you don’t know you need to do. The bigger the project, the more unknowns, and the harder estimation gets. So should you just not make estimates? Of course not! Instead, you can use an Eng Spec to enable accurate estimates by breaking tasks into incremental chunks.
At Mixmax, before we start coding on a big project, we divide that project into many small subtasks and manually write out how we’ll attack each one. This allows us to identify any unknowns in the subtasks, then potentially address them. Once we’ve done this, we make an estimate for each small task, throw in extra time for testing, reviewing, and cushion, and add it all up to get a project estimate!
When estimates are built like this, not only are they more accurate (since engineers are always more experienced with the subtasks than with the big projects), they’re dynamic. If an “unknown unknown” crops up in one subtask, estimates can be updated. Furthermore, if a subtask doesn’t provide value to users that justifies the time it takes, it can be easily descoped to a later release. Granular estimates lets us retain flexibility while reaping the rewards of transparency.
Own Unknowns
A specification is not a stone tablet to be presented to your teammates — it is a tool for planning and communicating together with them. That means that a good Eng Spec asks questions! Teammates are an incredibly valuable source of knowledge. We learn more, and make the right decisions faster, by admitting what we’re not sure of and explicitly asking for advice and feedback. This is the whole point of a having a team.
At Mixmax, our finished Eng Specs often contain open questions and admit to “known unknowns”. Some of these are big enough questions to block implementation. That’s OK! We don’t just start building when we finish the Eng Spec’s first draft — we share our specs with the team and ask for advice and feedback first. Often, teammates can leverage their prior experience to resolve these open questions.
Other times, “known unknowns” will be non blocking. For example, UX details don’t always need to be set in stone right away. Indeed, waiting to finalize those details until they can be seen in the context of the rest of the product can often lead to much smoother user experiences. By contrast, hammering out every last detail before building offers diminishing returns on time investment, hampers velocity, and leads to inorganic and clunky UX.
In summary: by focusing on users, setting SMART goals, estimating incrementally, thinking in code, and owning our unknowns, we at Mixmax have been able to use Engineering Specs as force multipliers. They let us design thoughtfully, plan thoroughly, evaluate progress, conduct retrospectives, communicate clearly, and save huge amounts of development time. If you want to reap these rewards, you, too, can write great specs!
Or, if you like communication, embracing uncertainty, and delivering lots of value fast, you can come work at Mixmax. :) Join us!
