Addepar | Developing a help content style guide

A screenshot of Addepar's Help Content Style Guide. This guide lives on Addepar's instance of Confluence, a company wiki. I wrote the initial draft of this guide, and our team of three product content strategists continue to iterate on it as needed.

When I started at Addepar, the product content team did not have a unified style guide or glossary for writing help documentation. Articles differed in format, voice, and tone depending on the content strategist writing them, confusing both users and internal Addepar employees.

I led the effort to bring more consistency to our help content's format, voice, and tone. I interviewed product content strategists, client support services personnel, sales leaders, and relationship managers to research their individual opinions of Addepar Help, the product help site.

Then, I wrote an initial version of the style guide, presented it to the product content and support teams for their buy-in, and developed an implementation plan with the rest of the team..

Key Considerations

Providing for necessarily complicated workflows. Addepar is a financial services product with workflows that touch multiple parts of the product and can take a long time to perform. For the style guide to be successful, it would have to accomodate both the writers and the users—the writers with easy-to-follow guidelines, and the users with easy-to-read results.

Identifying help content constraints. Early on, I learned from client services that the average user wants help content that is easy and quick to follow. In light of that, I knew help content had to be friendly, but utilitarian. Help content that had an overly personable voice might be distracting, whereas help content that was too robotic could be difficult to follow. 

Creating adaptable, replicable article templates. To create more consistent articles, I wanted to create templates that content strategists could use in lieu of creating from whole cloth. However, these templates had to work across a variety of different workflows, from the simplest sign-in workflow to the most complicated investment management guide. Otherwise, writers might not use the templates at all.

An example of a typical how-to guide as published on Addepar Help. In the actual guide, the image is an animated GIF explaining the workflow.

I began by diving into Addepar Help, exploring the content that we published every week. I found a slew of different voices, tones, and article formats, from sparse and utilitarian to charming and casual.

When interviewed about this disparity, client services team members stated that clients had actually mentioned this to them. We determined this was probably not ideal for a help site, which should be noticed only for its helpfulness.

I identified five distinct writing styles in Addepar Help. Then, I copied examples into a Google Slides deck, added recommendations to revise each example, and met with product content and client services to determine a voice that customers would find helpful and readable.

A sample slide from my voice and tone recommendation deck. This one depicts recommendations for improving writing that included corporate jargon.

From these recommendations and meetings, I recommended voice guidelines that presented Addepar Help as experienced, encouraging, and straightforward.  However, I wanted to also make sure that articles written to these guidelines would make sense to clients, who had previously only read our somewhat inconsistent help content.

Coupled with learning that our product content team had never met the client services team in person, I flew to Salt Lake City to embed myself with our client services team based there. I learned the voice and tone with which client services spoke to customers, and saw firsthand how clients reacted in real time to bad news.

I revised and presented the new guidelines for our help content to the services leads, and received their "looks good to me" after a week of shadowing customer success agents, listening to bewildered clients, and rewriting the guidelines.

After I returned to Mountain View, I presented the new version to our product content team. Then, I published the official first draft on our company's internal Confluence wiki.

Part of the Voice and Tone section of the Addepar Help Content Style Guide. I wrote an initial draft of these guidelines, presented it to Product Content, and iterated based on feedback.

Meanwhile, I also made recommendations for the format of each type of help article. I had just finished a major project creating user onboarding documentation for Addepar Help, and so I reused user research from that project, coupled with other companies' help sites, to create templates for each help article type.

After creating the initial templates, I brought them to product content for review and recommendations. Eventually, we were able to create a draft with full buy-in from the product content lead and the rest of the team.

A template for how to write a "How-to" section on Addepar. "How-to" sections are consecutive steps that teach users how to perform a workflow.

A sample of the content guidelines. This sample contains the template for an "attribute definition" article, which is essentially an extended glossary item. This also includes style guidelines.

Implementation

Addepar Help had hundreds of articles on the help site, and only three content strategists to rewrite each article to the new content style guide. To prioritize which articles to rewrite, I created a list of 50 of the most-searched-for articles with the longest time on page using Google Analytics. We set a 12-week timeline to rewrite all of them: roughly 1.39 articles per person per week to research, write, and review.

Before rolling them out, I worried that we could not A/B test these pages, due to budget restrictions. Neither did we have unlimited client time to test each page, their time and goodwill taken up by other product teams.

Instead, client services received direct feedback from clients, and in turn we received feedback from client services. In general, feedback was positive: clients enjoyed the new layouts and considered the standardized voice and tone easier to read.

The most critical feedback involved the specific examples we used to make features easier to understand, such as the "email distribution list" simile for subscription groups. While clients appreciated the attempt to create relatable similes, they didn't always find them effective. We revised these similes in our next iterations.

Takeaways

This was not the first voice and tone guide or style guide that I'd worked on, but it was the first I'd developed for a financial services SaaS. It's safe to say I learned a lot about the financial industry while writing it, including the specific language the industry relies on to clarify difficult concepts.

Find different ways to test when you can't actually A/B test. A common frustration as a product content strategist at Addepar is that we are unable to A/B test our help content due to budget constraints. Rather, we find other ways to test our content, such as asking about help documentation during product research calls ("Thanks for talking with us about this feature. By the way, if you were to need help with this, what kind of help article would be most useful? Something like this?") or shopping the content around relationship managers internally. It doesn't replace A/B testing, but it's the next best thing.

Communicate with client services. Experience their work firsthand. Client services / customer success represent the front line of any company's operation. They know the ins and outs of how clients react to different features, and as such know what kind of language mollifies a client (and of course, have exactly the user stories a product manager might be interested in building a feature around). Without shadowing client services, I would not have been successful in creating a style guide or voice and tone guide that clients would find useful.

Sometimes, you just can't avoid jargon. In rewriting articles to remove jargon, I ended up in trouble with the legal organization, which didn't appreciate my replacing jargon with more casual examples. This jargon was there for explicit legal reasons—we couldn't replace "subscribe" with "buy" or "sell," for example, when describing hedge fund investment—and I had to change my guidelines to suit the legal standard.

Designed by Andrew Hsieh © 2021-2022. All rights reserved.