Mixmax Advent 2017


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!

  1. Writing Effective Engineering Specs
  2. Introducing the Mixmax Sequence Picker SDK
  3. Handling 3rd-party JavaScript with Rollup
  4. Terraforming all the things
  5. Recruiting Engineers Using Online Challenges
  6. Database-backed job processing
  7. Precisely observing structural page changes
  8. Beating Spam-Detection Bots
  9. Introducing search-string: an advanced search string parser
  10. Improving Mongo performance by managing indexes
  11. Elasticsearch vs Redshift for Real-Time Ad-Hoc Analytics Queries
  12. 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!


Written By

Logan Davis

Logan Davis

From Your Friends At