WTF is a Spec?

As a fully remote company, you will hear this over and over again: collaboration is key! The number one reason spec’ing is important at Gradient is because we thrive on feedback. We aren’t working face-to-face, we can’t lean over a cubical or walk to someone’s desk to get instant feedback. While we have forms of project launch planning (workflows and Zoom meetings), putting everything in writing, having a thread of back and forth collaboration that can be referenced later, has been shown to be extremely effective and time saving!

Spec’ing removes as much ambiguity as possible and makes a massive, complex problem more manageable. Basically, the time and effort spent on creating the spec for an issue is less costly than the effort required fixing things or flailing around wildly to find a solution in the future. Consider the spec process an insurance policy on severely missing the mark.

Sports analogy: “on the green, not in the rough.”

Blueprint analogy: It is less costly to move a wall on a blueprint than moving a wall when the house is already in the process of being built.

Furniture assembly instructions analogy: You can have all the components you need to build a piece of furniture and an image of the final product, but the lack of a detailed plan for how to put it all together will make the process slow and over complicated. Think of the best assembly instructions you can, NOT IKEA.

A good spec’er showcases how they think and organize a complex task. Everyone has a different way of organizing their thoughts and we respect the process that works best for you, and we want to see that brilliance at work!

A good spec makes it easy for the team to understand what needs to be done, why, and how. You may need to go through a few iterations in order to get all of these pieces clarified, which is totally okay and, in fact, the whole purpose of spec’ing! Defining each of these helps ensure there is alignment across the team before work begins.

Generally, here’s how to structure a Spec:

Provide general context around the project so your teammates understand how the work in this issue fits into the broader picture.

• Project goals and/or research objectives
• Client and audience considerations
• Business application (how the client will use the work)
• Constraints or context for execution (data or platform limitations, deadlines, etc.)

Define what success looks like so we can confidently move the issue to Done.

• Deliverable format (e.g., plot, memo, deck, app, dashboard)
• Audience (e.g., client, internal, vendor)
• Stylistic or aesthetic approaches / intended level of polish (e.g., Crunch screenshots vs. custom plots)
• If a V2 is expected, what’s the goal of V1?

Map out how you expect to complete the work so others can give input, spot gaps, or help if needed.

• Material inputs
• Tools to be utilized
• Methods
• Collaboration expectations
• Known unknowns

While the general framework above applies to all specs, it is true that there are certain tasks that we spec out frequently, and each of them may have their own key features or pieces of information to include. To illustrate this, below is a chart that contains some of the most common types of specs that we write along with key features for each.

Remember that each project is unique, so while you may be writing a Data Cleaning spec, don’t limit yourself to the details listed below—include anything else that is needed, and omit anything that isn’t. Use your judgement, you know your project best.

Not every single issue needs a spec. Some smaller issues that have determined outcomes or recurring issues that are simple tasks don’t need a spec. However, it is better to have spec’ed and not need it than to waste your valuable time due to misalignment, rework, or unanswered questions.

Here’s some guidance to help determine if a spec is needed:

• The issue is new, non-routine, or ambiguous—you’re not just repeating past work.
• The issue will be worked on by someone other than the person who created it, or passed between multiple people.
• The task involves synthesizing inputs, making choices, or crafting something from scratch (e.g., building a research plan, creating a deck, drafting a survey).
• There’s more than one way to approach it, and alignment is needed before proceeding.
• You need feedback, guidance, or approval before execution begins.
• You are trying to unblock yourself by organizing your thinking or asking for help.
• There are client-specific nuances that need to be captured and referenced later.

When in doubt, spec! If you’re unclear on what you’re doing, how you’re doing it, or what “done” looks like—write a spec.

• The task is a simple, recurring one with no major decisions (e.g., sending a regular deliverable, fixing a label, uploading a file).
• The issue is administrative or logistical (e.g., refreshing a report, duplicating a template).
• The work has already been fully defined elsewhere, and the issue just tracks execution.
  • Note: It’s still incredibly helpful to include a brief spec pointing to the other issue where the details have been defined, or link to the issue itself.
• The scope is extremely narrow and you’re the only person involved.
• It is a “review” issue for another deliverable (again, helpful to at least have the other issue linked)

It is recommended that you focus on creating your specs on Mondays after sprint planning with the goal of having them in Specification Written status by Tuesday standup at the latest. This way you are front-loading your week with planning and giving your reviewers an early heads up that you need some of their time during the week for review and collaboration.

Focus on issues with Review or Problem Solving labels first, since these are the issues that you most likely or will need the most collaboration on.

Spec in a way that works best for you AND contains all necessary information you need to complete your work. Remember, you are brilliant and we want to see it!

Specs that saved our lives and why

• Determining function tests
  It took Iaroslav, Michal and Stefan ~30 comments to align on the outputs. If we didn’t do any spec’ing, a lot of work would’ve been put into this, without getting the desired outcome

• User Interface for Application
  It took a lot of back and forth to determine what actually needed to be delivered here. Once we aligned (which was not painless) we saw the merit of spec’ing it all out

• Willingness to Pay Analysis Spec
  After ~3 pages of comments we were finally aligned on what the outputs should look like. Spec’ing involved multiple plot mock-ups and tables to describe what the end product would look like

Other stellar spec examples:

• Plot-a-palooza
• Open ended analytical task
• Very broad proposal
• Data-related operations task
• Segmentation survey outline
• Jira Issue that contains Google Slides plots

Sometimes the unknowns are just as important as the knowns when you are planning out an issue. This also offers a good opportunity to have a spec approver check your assumptions on what you know, and may help move some of the unknowns to knowns.

Let’s go back to the blueprint analogy…no really, go back to it! Get that blueprint draft as far as you can before you start building, so you don’t have to use your valuable time and effort to move any walls.

We are all human and sometimes the comments and questions you receive during the spec review process can feel personal. Gradient strives to have a “no judgment zone” for all collaboration, especially during the planning stage of a project or issue.

Questions are asked by a reviewer to clarify something that may be a bit confusing or add additional clarification to the spec itself. Comments may be something you hadn’t thought about when deep in the thick of brainstorming.

Our goal as reviewers and collaborators is to help each and every teammate knock a project or task out of the park (one can never use too many sports analogies). It is not judgment, it is steps towards success.

Other ways to look at spec’ing that take a little bit of pressure off:

• “Like a prototype”
  
• “Shitty draft”
  
• “Outline”