Handling communication in groups of people is tricky. It's not just one team, so silos are formed in one way or another. Making sure everybody knows everything they need to accomplish their job becomes tricky. Was Jane in the conversation with John about the design of the new feature? Was the conversation out loud? Does everybody remember the same outcome?

Now let's add a new spice to the mix: being a remote company. And now everything gets trickier.


One of the ways we handle this is by writing specifications for features (or anything that's longer to describe than a paragraph or two).

The original goal of specifications was to make sure we did security reviews of software designs. In a way, this is also communication, but our minds were in the "security audit" area rather than "keeping stakeholders on the same page" area. Then we realized that if we add a couple of other sections, and notify more people about it, we could make sure that more teams were aware of the new upcoming feature and that they could raise any questions or concerns from their perspective.

This led us to write specifications for a lot of things, regardless of whether it impacted a security aspect directly or not.

But we need more agility!

Yes, specifications add time to a deliverable. But it saves time later down the line. Here are a couple of scenarios in which it has helped us save a lot of time:

  • Deployment tickets for new features got a lot shorter: we can link back to the specification and everybody involved already is aware of what is being deployed.
  • QA already knows about a feature by the time the deliverable reaches their lap, so they know how to test it.
  • The business and product side don't say "well this isn't what we wanted!" because they got to evaluate it in detail in the specification.
  • Customer Support is aware of new features and they can document anything they need before the release reaches the users.

"Oh dear! This is perfect!", you might think. No, it's not.

We sometimes have to discuss deployments more, sometimes the QA person that ends up with the task of evaluating the new feature is not the one that reviewed the specification, so they have some concerns or questions that weren't addressed. And so on.

It's also true that now you have the job of maintaining a specification up to date, or make sure you archive ones that are not valid. So it's definitely not a silver bullet.

So why bother? Well, because you need to start somewhere, and things are a lot better. We continuously work to improve the process and specs.

Information flow is a lot better. The end results are more secure. Stakeholders are on the same page. Documenting is part of the process of getting things done. That, to me, is a great start to a very pleasant song.


Reviewing specifications, just like with code, takes time. So can we do something to make it smoother? Yes, we can.

One thing that we do is that all specifications follow the same format. This helps reviewers get to a specific frame of mind when reviewing each section as they know what the goal of that section is. It also guides writers to make sure they address the different aspects that are expected from a specification.

Below is the template we use for technical specifications.

# Title

# (optional) Table of contents

If the spec is too long, a table of contents will help.

# Authors

- Jane Doe

# Document Status

Briefly mentions the status of the document: draft, ready for review, or approved.

# Motivation

Explains why this specification exists.

# Overview

Describes the overall idea, challenges faced, scope of the specification.

# Design

Describes in detail how the system proposed works and should be built.

# Licensing

If there are any licensing issues from implementing this specification, they should be detailed here. Or if the deliverable will have a specific license.

# Ops

Details on how deployment of this design should go.

# Security Assumptions

Assumptions the design was built upon.

# Security Claims

Claims the design makes about the system that should be true.

# Success Criteria

Defines what would make the implementation of this specification a success. Or what the MVP of it would be, if the specification is too big.

# Reviewers

Lists the reviewers from all the departments that should be aware of this specification.

It's all about quality

There's always a balance between two or more worlds that you can't satisfy 100%. In this case, it's about the time taken between "I have an idea!" and "users have a new feature", and making sure that users get a quality result on their hands.

Quality for a company like SpiderOak also means security. Honest mistakes happen, most of us are humans after all. Sometimes these mistakes impact the security and privacy of a user. That's huge problem for us.

We choose to move the balance towards taking the amount of time needed to make sure we provide high quality products.