Our product specs are only living sources of truth up until the tech spec moment. I think of it almost like a bell curve. The brief starts out quite unpolished and light, and as you learn more, you continue to add detail. When an engineer takes over and starts fleshing out the technical requirements, that's when you start to see a plateau or the peak of the fidelity of this document. It’s not a true handoff — as engineering works on the tech spec, they go back into the spec as the source of truth and we might add even more detail.

Once the tech spec is done in JIRA, you see the fidelity of the product spec starting to tail off. We might keep updating it a bit, but it's no longer the primary source of truth that people are building off of. However, we try to make sure it's a gradual tail-off rather than a cliff. This was such a big feature that, for posterity's sake, I think we updated a little better than we might with other specs.

The product brief is 100% owned by the PM. The spec comes in after the brief has been approved; the PM still owns it, but now they're working with design and a little bit of engineering to flesh out the details. We don't want full engineering resources yet, but of course we need their input to ensure things aren't going fully off the rails. A site branch is massive, but a page branch is pretty small — we needed engineering to be involved in those kinds of decisions.

We typically do 1-2 dozen discovery calls for an extra large project like this. We're a very community-led and influenced product, so we partner with them more than your average company. I definitely do this many customer calls per feature at Slack, for example.

This is where we really lean on tech leads. We think of tech leads as the architects and biggest partners to product. They tend to roll off of other features earlier than the rest of the engineers, as they support a PM on part of the product spec, and then become the primary driver of the tech spec.

We don't like to bring in too many engineers in this phase because they're also doing other things, and it's really expensive to pull engineers off of features to go do documentation investigation. A tech lead will use their best discretion to pull in experts from other areas as needed, but it's very ad hoc. Ideally, we don’t have more engineers dedicated to something until the tech spec is near final.

This section has come from feedback that I've gotten over my entire product career. Once something is written, a lot of questions come up, a lot of decisions get made, and it's hard to document what they are. They oftentimes exist in a bunch of different places: some are in JIRA, some are in the spec, some are in Slack, etc.

What we wanted to do here was be a bit more deliberate about actually writing down the questions and decisions, with reference to where they are. We’re a very Slack-heavy company, and having that bi-directional pointing to decisions and conversations was something that we wanted to have in the spec. It doesn't get referenced a ton; probably 8 out of 10 decisions are just like, “Noted. Great. Let's move on.” But miscommunication does happen, especially with asynchronous communication, and a few big decisions can create an asymmetric risk/reward balance if they’re not documented.

We approach sequencing from two different angles. We try to break things down into their smallest atomic unit that is a complete story, but we also tend to think of product development and product releases as correlated but different. In the spec, we're thinking more about what is the best way to build this thing? That means more small milestones, as opposed to a few larger ones.

As we're going through it, we start to bring in our GTM partners to determine how many of these inputs are actually launchable. A lot of inputs go into that: what else are we launching? What time of year is it? How close to our annual conference is it? So launching requires a very complicated decision-making process, but from a product development perspective, we're trying to down as many bite-sized milestones as we can so that we can show progress and start testing things as soon as possible.

This section is pretty unique to Webflow, and I think it's because the product is so complex, and there are so many interactions between all these different features. The PM still owns this section, but they’ll get a lot of input from different teams. The CMS, which is a huge part of the Webflow product, isn’t owned by the Enterprise team, so the PM got a lot of input from the CMS team in this section. They helped us think about potential usability risks that might require additional education assets. Our Quality team is also especially helpful here, especially our more tenured folks. In this case, we were able to lean on people who deeply understood where and why things had broken in the past.

Thinking about edge cases up front has become a bigger focus for Webflow as we found a lot of projects getting delayed and delayed and delayed. We have something like a pre-mortem at the spec stage to get ahead of all these potential issues and edge cases. That was a unique Webflow thing I had not done in the past

Larry Blyth

Britt Jamison

After the brief was approved, Larry and I built out this product spec for our first big enterprise feature.

PM: Larry Blyth | Design: [redacted] [redacted] [redacted] | Eng: [redacted]

Today, scaling teams struggle to efficiently build websites in Webflow because only one designer can work at a time. Enabling multiple designers to divide and conquer in Webflow with page branching will unlock immense productivity for scaling teams.

For an overview of the background, problem, and opportunity please see the Product brief

Not exhaustive, for open technical questions please see 

Note: we switched to using our slack channel to surface decisions with more visibility

Search ‘DECISION:’ in #proj-page-branching to check them out

See here for a summary of user stories, milestones they belong to, and relative priority

so that I can start designing in parallel

 until it is ready to be merged into the main site

 so that I can have my branch approved and merged

 so that my work is ready to be published to the live site

 so that my team can effectively divide and conquer across page branches and the main site

—-----------------------------------------

As a designer (in design mode or edit mode)…

Be aware if another user has already branched a page, so that I know not to modify it or create another branch of it (to avoid conflicts)

), so that I can work on that page in parallel

Create a new page branch, so that I can design the new page while my teammates work on the main site

), so that it is has a name when it is added to the main site

To design the page branch, I want to be able to:

Classes, combo classes, static content, assets

Classes, symbols, interactions, assets, CMS content (including binding/unbinding)

DOM (e.g. adding/moving/deleting elements)

 for full details and differences between 

Navigate between the main site and page branches, 

Make changes on the main site that I can’t on a page branch (e.g. modifying a symbol or the CMS)

View and copy-paste elements from other pages into the page branch to speed up development

 on my branch to reflect the latest from the main site, so that I can design using the most up to date designs and avoid conflicts upon merging 

I want to know when there are updates to the classes or symbols used on my branch, so that I can take action to update them 

If I update the classes on my branch, I want to know if there are conflicts (i.e. if I modified the same class) and to be able to manage those conflicts, so that I minimize conflicts that arise during merging 

 request/handover control of a branch, so that my teammates can collaborate on my branch (e.g. editing content, adding custom code, creating interactions, reviewing, etc) 

 only one user is allowed on a branch at a time [see details here]

 polite handover exists on the branch level i.e. users can enter a branch in edit-mode and request design control of the branch

Preview the page branch, so that I have high confidence that there are no issues with the page before merging

Know which classes on my branch conflict with the main site, so that I can take action on each

Know what the difference is between them, so that I can make an informed decision about which to choose (e.g., ‘sign-up-button’ has padding of 4px on main site vs 2px on my branch)

Choose which class should persist, so that the design system remains intact post merging

Write a commit message describing the changes I made, so that the reviewer has the context

Know the status of my merge request (e.g. pending, approved, denied)

I want to review, approve, and merge a branch into the main site, so that I can publish the updated page

Read a commit message from the author, so that I have the full context to review the changes

Know what changes were made, so that I have high confidence they won’t negatively impact the site

Preview the page branch, so that I have high confidence that it is ready to be merged

Be aware of any class changes that are going to overwrite classes on the main site, so that I understand the impact of the merge 

I must have design-control, because merging the page branch will cause changes to the main site

I want to be informed about what will happen when I merge the page branch, e.g.,

any modifications made to the page on the main site will be lost

class changes from the main site (not updated on the page branch) will be updated upon merging (similar to with 

Finally, I want to approve and merge the page branch into the main site, so that I can publish the updated page 

Restore the main site and the page branch to their state immediately before the merging, so that I can quickly revert any issues that could have been caused by the merging

, to lower the risk that a merge causes site issues, including: 

Only certain users can approve merges [new permission]

Consideration: A designer can select which ‘approver(s)’ need to approve a merge

Consideration: An approver can be notified when they need to review/approve a merge

View a list of page branches, including who created them and when they were created

Delete a page branch, so that my teammates can modify the page on the main site or create another branch of this page

Product Spec: Page Branching at Webflow

Product Spec: Page branching

Overview

Links to related docs

Sign up to see more