From directional steps to deep links

In the Cloudflare docs ↗ - as with every docs site - we have standards ↗ for how we write.

Specifically, we have standards for how we write navigational instructions. And - until recently - those standards were to write something like the following:

1. Log into the Cloudflare dashboard ↗.
2. Select your account and zone.
3. Go to DNS > Records. …

We chose that standard a while ago because we didn’t want to assume that someone would already be inside the Cloudflare dash before navigating in. We also reasoned that navigational instructions would help users move around easier in the dash.

A new challenger approaches

That strategy served us well as a team standard for a few years… but with one clear weakness.

In some situations — predominantly phased rollouts of features — our docs struggled to help our users:

• Keeping one variation of instructions invariably confused the other group.
• Keeping both variations of instructions confused everyone (and was way harder to maintain).

These struggles were an acceptable outcome for small rollouts, but we then had to support a major dashboard navigation overhaul.

It was shaping up to be a logistical and experiential nightmare.

Deep links to the rescue

In light of that challenge, we revived an option from our original discussion of our writing standards: deep links into the Cloudflare dashboard.

You see, the Cloudflare dashboard can actually navigate you pretty far just from a URL, so long as that URL is structured into something like the pattern below.

https://dash.cloudflare.com/?to=/:account/:zone/dns/records

We’d originally rejected this idea because we couldn’t get an auditable source of truth from the dashboard team. However, with the upcoming rollout (and the known struggles of working on phased rollouts), we revisited our requirements with them.

It took a little bit of negotiation, but because we were committing to so much work (thousands of updates), they agreed to help us and give us a list of routes for the dashboard.

Implementation

We turned that source of truth into a simple component, Dash Button ↗.

It takes the route as an input and gives you back a stylized button, meaning our instructions now looked a bit more like:

1. In the Cloudflare dashboard, go to the WAF page:
   Go to WAF

As the simple ones are, this change took a metric f*ck-ton of work. Incredible kudos to the rest of the team here.

Results

The results of this work were 4-fold.

Phased rollout success

The phased rollout went along without anyone complaining about the docs, which is generally your sign of success for docs.

Also, so long as internal teams set up redirects on their paths, we could continue to support users without knowing where they were coming from. We didn’t need to know which condition someone was in, the dash team did (and could route them appropriately).

Huge adoption

As of this writing, the Dash Button is one of our most popular components, used almost 1000 times across our docs.

Man, do I love that we track usage numbers!

Customer support loved it

A huge surprise for me, our docs got a shoutout during an open floor discussion with a few support folks.

They explicitly mentioned how having deep links throughout our docs prevented them from:

• Having to work through the dashboard navigation themselves
• Having to walk customers through the dashboard navigation

Especially that last one was so painful, they told us, “No no, click over on DNS. No, not WAF. DNS. Okay, then Records.” Much simpler to give a customer a link.

Auditable changes

The other unexpected benefit was how much easier this has made it to audit (and then fix) changes in the dashboard nav.

Of course, we all know that you should let your writer know that something in the dashboard has changed… just as we all know that often that doesn’t happen. And instead then you’re reacting to changes reported by angry customers.

But — when you have a source of truth to audit against — boom! You get PRs like this one ↗, where we realize a bunch of those routes are wrong without someone having to stumble upon them.

39 times we fixed something before someone reported it, booyah!