Content design is a relatively new discipline, but one that deeply affects how users perceive, choose, and use products. People who work in content design can take many names (content designers, UX writers, product writers, just to name a few) but in a nutshell, our job is to help users accomplish goals on an interface by providing them with the right guidance at the right time. Unlike visual designers, content designers are not responsible for the graphic layout or the look and feel of a given interface — instead, we own what we call the conversation between product and user along each journey to ensure that the user has all the information they need to reach their goal.

The interesting thing is — when interfaces are concerned, the more effective the text, the less noticeable it will be to users. Great content on an interface “just works”; it disappears into a delightful user experience while leading happy users to success, whatever it is they’re trying to get done with a given product. Content designers achieve that by making sure they know user needs inside out and which problems the product is trying to solve. Next, in partnership with visual designers, they sketch out user flows and wireframes.

Only as a last step do they sit down and write.

My journey at Cloudflare started in July 2020, when I was hired as the technical writer for the Zero Trust products. I spent my day-to-day life setting up and testing features on our interface. In a sense, my job was to observe user experiences and write about them. Over time, I started noticing there was room for us to make those experiences truly exceptional. Could we take a holistic view of them and spend some time consolidating the way we talked to users throughout the interface?

Good documentation fills the gap between user needs and product features. But imagine a product users could just use, without necessarily needing to pull up instructions. Imagine a product that consistently “talks” with users, providing them with the necessary information at each step, signaling a clear path forward with predictable outcomes for each action, and reassuring them when an error occurs.

After all, Cloudflare’s vision is to make our products ridiculously easy to use, and content design could play a huge role in that. I started a conversation with my manager about it, and asked if I could volunteer to own UI content, too. I was eager to take up the challenge.

I’m now almost two years into my journey at Cloudflare, and looking back, there’s definitely a few things that helped me take my first steps as a one-woman content design team.

There’s more to content design than just putting pen to paper and writing. One of the things that makes UI content successful is consistency, because consistency drives familiarity. And as users, we love experiences and products we recognize. In those early days, I had one question in mind: How do I write consistently for this interface?

• Product voice and tone. The first thing I needed to define was our product’s identity. Are we a cheeky young product that sprinkles exclamation marks and interjections across the interface? Are we an authoritative, established product that gives concise, reassuring guidance? Read more on how I defined our product voice in this other blog post.

• Guidelines. Next, I needed to get real about tying it to actually writing for the dashboard. It is one thing to say that the product sounds “friendly”, but what does that mean in practice? Because all UI content exists within a design environment, I structured these guidelines based on our design system for the Zero Trust dashboard. This came in handy when I (or anyone else, really) needed to write for a specific component. These guidelines answered exciting questions like, “Do we ever use em dashes?”, or “Do I add ‘please’ when asking for user input?”

• Heuristics. I knew the content in certain areas of the dashboard was not optimal, but it was often hard for me to communicate to stakeholders what I meant exactly. Coming up with an objective set of parameters and even a scoring system can really help quantify how much work those areas need and what type of work. These parameters evaluate things like a feature’s purpose, clarity, accessibility, and compliance to voice and tone.

In my first days wearing my content designer hat, I remember being pulled in last-second to work on error messages right before a feature went live. I had to unpack who would see that message, at what point in their experience they would see it, and what information they needed in order to get past it — only then could I start writing, and even then, even with my toolkit at hand, we would end up with suboptimal copy. Feedback from users came loud and clear:

I needed to find a way to be more involved in product design and development processes. In a word — I needed to start thinking about user experience.

My first move was to join our front-end team stand-ups. Being part of feature development since kickoff made a world of difference — I was in the room when PMs explained the problem(s) a certain feature needed to solve, when functional specs were presented to the group, and when developers approached issues or improvements. All of this gave me immense context on how our interface works.

I also focused on building deeper relationships with our product designers. We shared much the same challenges, and if we partnered together, we could tell a much better story around our products and how they work. When I set out to define the product principles for our dashboard, designers were a source of enthusiastic and priceless help, and when new features came about, we joined forces from the very beginning of the design process.

In time, everybody learned to row in the same direction. We became the UI team. One of the features we shipped during that time was a new home for the Zero Trust dashboard. Next, we tackled empty states, making sure they were consistent and informative across the interface. We overhauled all of our error messages, and we redesigned the onboarding experience. All with the user in mind, and a clear vision to ship products that are truly easy to use.

Over the past few months I had long conversations with my manager in the Product Content Experience team. As much as the Zero Trust dashboard was coming together in terms of UX content, it was a lot of work. As a content designer, I weighed in on every design decision, partnered across simultaneous projects, iterated on our content strategy and (at the time) wrote documentation for all the new features. We agreed that there was value in the space we’d carved out for content design, but we needed a plan to scale a strong content design habit across the org, and ensure all products had the same coverage when it came to content design.

Today, I’m happy to share that we’re building a whole content design team. There’s lots of hard work ahead of us, but it’s hard work I’m looking forward to, because the story of content design at Cloudflare is only just beginning. Starting. We’ve just begun. Stay tuned, the best is yet to come! No, that’s cheesy. I liked the first version better. How about “we’re just getting started”.

You get the gist.

(Yes, we’re hiring in Lisbon and in the US! Come join the team.)

A big part of the job of a technical writer is getting feedback on the content you produce. Writing and maintaining product documentation is a deeply collaborative and cyclical effort — through constant conversation with product managers and engineers, technical writers ensure the content is clear and serves the user in the most effective way. Collaboration with other technical writers is also important to keep the documentation consistent with Cloudflare’s content strategy.

So whether we’re documenting a new feature or overhauling a big portion of existing documentation, sharing our writing with stakeholders before it’s published is quite literally half the work.

In my experience as a technical writer, the feedback I’ve received has been exponentially more impactful when stakeholders could see my changes in context. This is especially true for bigger and more strategic changes. Imagine I’m changing the structure of an entire section of a product’s documentation, or shuffling the order of pages in the navigation bar. It’s hard to guess the impact of those changes just by looking at the markdown files.

We writers check those changes in context by building a development server on our local machines. But sharing what we see locally with our stakeholders has always been a pain point for us. We’ve sent screenshots (hardly a good idea). We’ve recorded our screens. We’ve asked stakeholders to check out our branches locally and build a development server on their own. Lately, we’ve added a GitHub action to our open-source cloudflare-docs repo that allows us to generate a preview link for all pull requests with a certain label. However, that requires us to open a pull request with our changes, and that is not ideal if we’re documenting a feature that’s yet to be announced, or if our work is still in its early stages.

So the question has always been: could there be a way for someone else to see what we see, as easily as we see it?

I was working on a complete refresh of Cloudflare Tunnel’s documentation when I realized the product could very well answer that question for us as a technical writing team.

If you’re not familiar with the product, Cloudflare Tunnel provides a secure way to connect your local resources to the Cloudflare network without poking holes in your firewall. By running cloudflared in your environment, you can create outbound-only connections to Cloudflare’s edge, and ensure all traffic to your origins goes through Cloudflare and is protected from outside interference.

For our team, Cloudflare Tunnel could offer a way for our stakeholders to interact with what’s on our local environments in real-time, just like a customer would if the changes were published. To do that, we could expose our local environment to the edge through a tunnel, assign a DNS record to that tunnel, and then share that URL with our stakeholders.

So if each member in the technical writing team had their own tunnel that they could spin up every time they needed to get feedback, that would pretty much solve our long-standing problem.

To test out that this would work, I went ahead and tried it for myself.

First, I made sure to create a local branch of the cloudflare-docs repo, make local changes, and run a development server locally on port 8000.

Since I already had cloudflared installed on my machine, the next thing I needed to do was log into my team’s Cloudflare account, pick the zone I wanted to create tunnels for (I picked developers.cloudflare.com), and authorize Cloudflare Tunnel for that zone.

$ cloudflared login

Next, it was time to create the Named Tunnel.

$ cloudflared tunnel create alice
Tunnel credentials written to /Users/alicebracchi/.cloudflared/0e025819-6f12-4f49-8183-c678273feef4.json. cloudflared chose this file based on where your origin certificate was found. Keep this file secret. To revoke these credentials, delete the tunnel.

Created tunnel alice with id 0e025819-6f12-4f49-8183-c678273feef4

Alright, tunnel created. Next, I needed to assign a DNS record to it. I wanted it to be something readable and easily shareable with stakeholders (like abracchi.developers.cloudflare.com), so I ran the following command and specified the tunnel name first and then the desired subdomain:

$ cloudflared tunnel route dns alice abracchi

Next, I needed a way to tell the tunnel to serve traffic to my localhost:8000 port. For that, I created a configuration file in my default cloudflared directory and specified the following fields:

url: https://localhost:8000
tunnel: 0e025819-6f12-4f49-8183-c678273feef4
credentials-file: /Users/alicebracchi/.cloudflared/0e025819-6f12-4f49-8183-c678273feef4
.json  

Time to run the tunnel. The following command established connections between my origin and the Cloudflare edge, telling the tunnel to serve traffic to my origin according to the parameters I’d specified in the config file:

$ cloudflared tunnel --config /Users/alicebracchi/.cloudflared/config.yml run alice
2021-10-18T09:39:54Z INF Starting tunnel tunnelID=0e025819-6f12-4f49-8183-c678273feef4
2021-10-18T09:39:54Z INF Version 2021.9.2
2021-10-18T09:39:54Z INF GOOS: darwin, GOVersion: go1.16.5, GoArch: amd64
2021-10-18T09:39:54Z INF Settings: map[cred-file:/Users/alicebracchi/.cloudflared/0e025819-6f12-4f49-8183-c678273feef4.json credentials-file:/Users/alicebracchi/.cloudflared/0e025819-6f12-4f49-8183-c678273feef4.json url:http://localhost:8000]
2021-10-18T09:39:54Z INF Generated Connector ID: 90a7e3a9-9d59-4d26-9b87-4b94ebf4d2a0
2021-10-18T09:39:54Z INF cloudflared will not automatically update when run from the shell. To enable auto-updates, run cloudflared as a service: https://developers.cloudflare.com/argo-tunnel/reference/service/
2021-10-18T09:39:54Z INF Initial protocol http2
2021-10-18T09:39:54Z INF Starting metrics server on 127.0.0.1:64193/metrics
2021-10-18T09:39:55Z INF Connection 13bf4c0c-b35b-4f9a-b6fa-f0a3dd001951 registered connIndex=0 location=MAD
2021-10-18T09:39:56Z INF Connection 38510c22-5256-45f2-abf8-72f1207ca242 registered connIndex=1 location=LIS
2021-10-18T09:39:57Z INF Connection 9ab0ea06-b1cf-483c-bd48-64a067a87c39 registered connIndex=2 location=MAD
2021-10-18T09:39:58Z INF Connection df079efe-8246-4e93-85f5-10caf8b7c354 registered connIndex=3 location=LIS

And sure enough, at abracchi.developers.cloudflare.com, my teammates could see what I was seeing on localhost:8000.

After creating the tunnel, I needed to make sure only people within Cloudflare could access that tunnel. As it was, anyone with access to abracchi.developers.cloudflare.com could see what was in my local environment. To fix this, I set up an Access self-hosted application by navigating to Access > Applications on the Teams Dashboard. For this application, I then created a policy that restricts access to the tunnel to a user group that includes only Cloudflare employees and requires authentication via Google or One-time PIN (OTP).

This makes applications like my tunnel easily shareable between colleagues, but also safe from potential vulnerabilities.

Back to the Tunnels page, this is what the content team’s Cloudflare Tunnel setup looks like after each writer completed the process I’ve outlined above. Every writer has their personal tunnel set up and their local environment exposed to the Cloudflare Edge:

The team is now seamlessly sharing visual content with their stakeholders, but there’s still room for improvement. Cloudflare Tunnel is just the first step towards making the feedback loop easier for everyone involved. We’re currently exploring ways we can capture integrated feedback directly at the URL that’s shared with the stakeholders, to avoid back-and-forth on separate channels.

We’re also looking into bringing in Cloudflare Pages to make the entire deployment process faster. Stay tuned for future updates, and in the meantime, check out our developer docs.

Today, we’re announcing a new feature within the Teams Dash. We called it “Home”. We created Home with a simple goal in mind: design an adaptive and informative landing page where users can see a round-up of their environment.

In this last post of our series, we’ll show, rather than tell, how we collaborated as a team that rows in the same direction and towards the same goal — to create a great user experience.

In this blog post, we’ll walk you through your new Teams Home by calling out a few of the guiding principles we had in mind as we designed it. Transparency, adaptiveness, guidance and warmth aren’t only foundational words in the Cloudflare for Teams product principles — they’re part of our day-to-day brainstorming and discussion around user experience.

Here’s how the Teams Home reflects these principles.

What you’ll find in the new Teams Home is a single space to view your network and applications traffic. We wanted to build an experience that allows users to get a comprehensive view of all things protected by Teams — a single pane of glass that’s always available, and that users can quickly pull up to spot any anomalies in their network traffic. Or simply to keep it under control.

We’ve also made it simpler for you to keep an eye on user count, and added a direct link to our plans page should you need to make any changes to the subscription you’ve chosen.

The Teams Home brings all users signals into one view, threading together concepts that were once sparse across the Dash.

We called it “Home,” because we wanted it to feel like a space you visit each day that brings you clarity and peace of mind. Too often, security products can feel clinical and stark, and we wanted to avoid that. Through the use of color theory and language analysis, we actively worked to convey a feeling of approachability, while still keeping the Dash functional and straightforward.

When writing for UX, we need to be considerate of a user’s emotions as they follow a given flow in our product. Some users may appreciate certain elements as they explore the dash on a not-so-busy day; other users may not if their environment is at-risk and they simply need to identify what’s wrong, fast.

With this in mind, we’ve sprinkled bits of conversational, friendly copy where appropriate. For example, the biggest textual element in the Home page is a greeting — consistent with the header in our Quick Start page (“Welcome aboard!”), the tone is designed to be cheerful and welcoming.

Another subtle example of this is our loading screen. Nobody likes to wait, so we wanted to build this interaction for our users as well. With an animation that brings in elements representative of Cloudflare’s network, and alternating lines of copy that refer to the semantics of building and cleaning a physical home, we wanted to add a quirky touch where it doesn’t interfere with what really matters.

The Teams family has grown and expanded since its inception, and we wanted to highlight complementary features that are a key part of our user journeys. In the footer, you’ll find easy access to things like Cloudflare Radar, the Teams Help page, and a quick-start guide packed with simple starter packs. These additional features help craft a holistic picture of the Teams story.

In our product principles, we give great importance to ease of use. And we, as a team, have an ambitious goal in mind — make Zero Trust security principles approachable for everyone.

To us, a product is easy to use when it guides users to success through clear paths in the interface. This is why we’ve pre-established some of these paths — we want to help our users take their first steps within Teams. With just a few clicks from the Home and Quick Start pages, users who signed up primarily for Secure Web Gateway functionalities can add Zero Trust rules in front of their applications, and vice-versa.

We’ve also incorporated an entirely new approach to some of our empty states. Instead of just telling our users there’s no data to show, we help them take actions to start populating those empty charts.

As threats on the Internet evolve, so will the needs of our users. Throughout this process, we thought critically about how the Teams Home could be flexible in nature, and scale was a key priority. We’ll continue to ship new features — and when we do, those features will have a place in the Teams Home, in large part due to the modular approach we adopted. Moving forward, we will continue to add more data signals into the Teams Home and aim to put more control into your hands to customize your unique Home experience. We’re also integrating easier ways for you to give us feedback on the overall experience and are excited to learn more from our users.

The Teams Home is available today for all users on the Teams Dash. If you don’t have a Cloudflare for Teams account yet, click here to get started.

You’ll know you’re Home when you see the Welcome Page.

My name is Alice Bracchi, and I’m the technical and UX writer for Cloudflare for Teams, Cloudflare's Zero Trust and Secure Web Gateway solution.

Today I want to talk about product voice — what it is, why it matters, and how I set out to find a product voice for Cloudflare for Teams.

On the Cloudflare for Teams Dashboard (or as we informally call it, “the Teams Dash”), our customers have full control over the security of their network. Administrators can replace their VPN with a solution that runs on Zero Trust rules, turning Cloudflare's network into their secure corporate network. Customers can secure all traffic by configuring L7 firewall rules and DNS filtering policies, and organizations have the ability to isolate web browsing to suspicious sites.

All in one place.

As you can see, a lot of action takes place on the Teams Dash. As an interface, it grows and changes at a rapid pace. This poses a lot of interesting challenges from a design point of view — in our early days, because we were focused on solving problems fast, many of our experiences ended up feeling a bit disjointed. Sure, users were able to follow paths within any given feature, but those features did not always work across the Dash in a seamless way.

Early this week we talked about how we’re leaving our “solution pollution” days behind and moving towards a design-led approach. To me, as the writer on the team, this means it’s time to step up our UX writing game and find our own product voice — a unique voice that reflects our product identity and speaks to our users in a recognizable “Teams way”.

As users, we love experiences and products we recognize. We’re loyal to them. It’s all about consistency, and the sense of familiarity that comes with it. When design and copy work hand in hand to convey a consistent feel, we soon learn to recognize the personality of an interface. Because every little detail has been curated for us, we’re rarely caught by surprise  — our experience just feels smooth.

Think about it in terms of human interactions. When picking up a call from a friend, we immediately recognize their voice. We don’t think about the why or how — we just unconsciously do, and start chatting away. However, imagine that friend suddenly uttered a sentence in a completely different voiceprint (spooky, right?). Imagine they started using words or expressions that never belonged in their vocabulary. We would notice right away.

Interactions through UX writing work in a similar way. Users notice right away when a piece of copy doesn’t sound as it should. So when working on copy for our interface, we need a consistent, recognizable product voice. A product voice is a set of principles and guidelines that standardize how we sound to our users. It will determine whether we put exclamation marks in our greetings (“Welcome!”), whether we include interjections in our error messages (“Uh-oh!”), whether we address the user with “you” or prefer a more impersonal approach. It will show our personality and shape what users can expect from us.

And the Teams dashboard needed just that — to find its own voice.

A voice isn’t going to be very successful for a product if it only sounds right to the writer crafting it, I reasoned. It needs to ring true to the people who build and breathe the product every day — our product managers, our designers, our engineers. In the end, a product voice will truly shine only if it’s aligned with product principles. And as a product team, we’d been so caught up shipping features and solving problems that we’d never sat down to brainstorm on our principles.

So the path was clear to me.

1. First, we needed to define our product principles.

2. From our principles, we would derive a product voice that matched our core values.

3. Last but not least, we would draft UX writing guidelines on how to write in our newly found product voice.

My idea was for this process to be as collaborative as possible, so I set up a series of brainstorming sessions with my teammates. I met with the product managers first, then with designers, engineers, and finally the marketing/go-to-market team. Each group gathered around a virtual board, and received the same prompts from me. I asked participants to focus on the ideal product they wanted Teams to grow into. Everyone worked independently on their own corner of the board — I was interested in every participant’s uninfluenced inputs.

Here are the prompts I gave:

1. List all the words you associate with Teams.We called this question the “brain dump.” I gave people two minutes and a half to be  instinctive, creative, and give me all the words they could think of.

2. Teams helps users by _______.With this question, I wanted people to focus on our everyday life. What do we do for our customers? Which problems are we trying to solve?

3. In terms of experience, I’d love users to associate Teams with ____ (brand).Again, I was after instinctive associations. Ideally, I wanted a list of websites I could later explore to see whether we could draw inspiration from them in terms of content.

4. Teams is unique because [it’s] ________.I asked people to focus on the qualities that set us apart in the market. What makes the product stand out?

Once I had all the answers, I classified sticky notes by lexical and conceptual association. Some patterns emerged. We had sticky notes describing who we are, who we’re not, what we do, our features, our technology, and what we care about. Once every sticky note had been grouped, I had a pretty good idea of the themes I could work with to draft our product principles.

I labeled each theme/principle with an adjective that could represent it and that could answer the question: what kind of product do we want to be for our users?

1. Reassuring. This was the first principle I worked on. Semantically, it reflects the core purpose of Teams — we’re a network security product, so our job is to protect. Under this principle I gathered all the words pertaining to the concepts of security, protection, and reassurance. People even used metaphors to express this concept: we’re a bodyguard. An armored truck.

2. Transparent. Another popular theme was our extensive analytics features, and the visibility they give to our admin users. This principle groups words whose root is in one way or another connected to the sense of sight: observing, monitoring, visibility, keeping an eye on. Interestingly enough, other words were more oriented towards the semantics of forensics: investigate, find, detect. For the main descriptor, I finally settled on transparent, because our product is a pane of glass (another metaphor that was used) that the admin can see through and know instantly whether something needs investigating.

3. Easy to use. This is a very ambitious principle for us. Network security is not an easy topic — it is our job to make it easy. All groups I brainstormed with gave huge importance to simplicity in one shape or another. Many stated our interface needs to be clean, accessible, approachable, digestible, direct. But we also vow to be inclusive, helpful and guiding, and never to assume knowledge.

4. Trailblazing. There was a clear theme around Teams being new on the market, but already showing the way. Modern recurred in most brainstorming sessions. Closely related descriptors, but stronger, were visionary and trailblazing, which I ended up choosing as the title of this principle, because it conveys the energy of a product that’s energetic and fresh.

5. Frictionless. This principle is all about a product that just works. Some words I’ve grouped under this principle describe two ways in which Teams aims at removing friction. First, Teams should aim at integrating with other systems_._ Second, Teams should be invisible. Our product is designed to be hardly noticeable by end users, and works behind the scenes.

6. Adaptive. This principle has two sides to it. The first is represented by resilience and Teams’ ability to adapt to circumstances (think concepts like adaptable, ready to change, and built in 2020). The second side is more about our ability to adapt to user needs. Here’s where our user-centered nature comes out: we let user needs shape our evolution as a product.

I went back to my sticky notes, this time to find and group words that could help us define the product’s personality, or more specifically, its attitude towards communication. Out of those groups, I chose five descriptors:

1. Straightforward. We know the value of effective and concise language. We give the right amount of information at the right time.

2. Helpful. We offer tips and guidance, and we ensure users are never left to figure things out by themselves.

3. Friendly. We’re happy our users are around. We empathize with them. We’re the warm and welcoming ones.

4. Fresh.  We’re a new, informal, geeky product. We address the user as if they were sitting beside us. We’re like a nerdy friend offering to fix your computer.

5. Controlled. We’re in control. No panic, no crazy excitement. We do not overreact.

As a next step, I crafted a voice matrix, slightly adapting Torrey Podmajersky’s approach in Strategic Writing for UX. I assigned a column to each voice trait and defined what each of them entails in terms of content, vocabulary, syntax, grammar, punctuation, and capitalization choices. This voice matrix summarizes the dos and don’ts of UX writing for the Teams Dashboard.

As I was filling out this chart, I noticed that most guidelines I came up with for the friendly trait also worked well for the fresh voice trait. Ultimately, I thought, it all boils down to a certain feeling of warmth in our communication — a feeling made possible both by our friendly nature and by our fresh, informal approach. In the end, I decided to merge those traits into the friendly principle.

This project has been an incredible journey to the heart of the product. I cherish the many creative conversations I had with my teammates about Teams. It was a chance for us to hit pause for a second, forget about deadlines and our everyday tasks, take a step back and focus on why we’re building what we’re building. It feels really good to have our principles written down, and we want to publish them soon on our product page for you to explore them.

Naturally, the project has also helped my writing tremendously. Every time I sit down to write a line of UX copy, I don’t just refer back to these four voice descriptors and their guidelines — I also write with the six product principles firmly in the back of my mind.

I’ve bookmarked the board with our sticky notes in my browser. It’s always there for me, and it contains the raw material I fall back on whenever I need inspiration.

This is just the beginning and the high-level structure of our strategy. In time and with iteration, we’ll build out these principles to become full-fledged UX writing guidelines, as well as a set of patterns that will allow us to achieve true consistency throughout the Teams Dashboard. Keep an eye on copy changes and see if you can hear our new voice take shape.

Next week we’ll introduce our Design team and their vision. Stay tuned!