Technical Communications: Documentation, UX, and Cohesive Brand Experiences

“You can have a very clean product, a very task-focused product, and people look at it and say ‘yeah, I get that, I know how to use it’, and they look at your docs and it’s a 400 page user guide. That’s gonna undermine your credibility.” – Kate Wilhelm

This past Wednesday, Communitech’s Technical Communications Peer-to-Peer group was treated to a presentation by Kate Wilhelm: Documentation, UX, and Cohesive Brand Experiences (or how to be a docs UX ninja).

As the teaser blurb says, “People who create documentation have an important role to play in how customers interact with products and experience brands”, and Kate was here to show us how technical writers can influence brand perception, promote cohesive experiences, and act as user advocates.

In Kate’s opening remarks, she reminded us that “everyone can participate in the user experience”, and throughout her session she had plenty of examples that illustrated why this is especially true for documentation writers and other folks who have a hand in technical communications.

[Related: check out the previous Technical Communications P2P, Stories All the Way Down]

What is UX?

Kate defines user experience (UX) as “the user-driven design of the experience users have when they interact with products, websites, or other touch points”. She clarified that, ideally, user-driven involves data and research that identifies and understands the typical users.

To frame the rest of the discussion, she also briefly summarized what the user experience function does:

• Defines, reframes, and refocuses the problem space
• Brings customer awareness and perspective to projects
• Balances customer needs with business objectives
• Crosses channels to promote cohesive experiences

Note that the definition and description was not “user experience is concerned with, and only with, the user interface”; this is a fairly common misconception, but Kate’s definition and points above suggest that the user experience itself is much more than the experience of using an interface (it extends to, for instance, using the company’s website, documentation, demo tools; the unboxing experience, etc.).

Kate also cited Peter Morville’s user experience honeycomb, which describes facets of the user experience.

OK, with everyone on the same page about UX, Kate moved on to examine the role of documentation in the overall user experience.

UX and Docs

This peer-to-peer group is largely populated by technical writers, so the next part of Kate’s session addressed the many synergies between user experience professionals and those folks responsible for documentation.

For instance, both parties care about users, and both have a holistic (i.e., end-to-end) product view; contrast this view with many other roles, which might focus on only one piece of the larger puzzle, for instance a function within a product or a single product within a portfolio. This holistic view is tremendously valuable, especially for user advocacy.

A user experience perspective and UX principles can help make documentation much more accessible and effective: understanding who the documentation is for helps narrow the focus; understanding a user’s expectations, needs, and goals helps determine and refine content. In short, a UX outlook provides principles and edicts upon which to draw while crafting effective user documentation.

In short, a UX outlook provides principles and edicts upon which to draw while crafting effective user documentation.

One such principle is “no ROT” (redundant, outdated, trivial) content: everything must have a reason to exist. Without knowing the acronym until now, I’ve been advocating this same approach in my own role, while I craft or edit documents, video scripts, abstracts, press releases, etc.

A second principle concerns language and tone. Kate recommends using terminology that’s accessible to the users, and brought this principle to life with an example drawn from our shared experiences. Paraphrasing, “We start a job at a new company and everything’s so foreign, but we quickly become part of that world and start using the same terminology, acronyms, and jargon. In doing so, we risk leaving the reader/user behind.”

“We start a job at a new company and everything’s so foreign, but we quickly become part of that world and start using the same terminology, acronyms, and jargon. In doing so, we risk leaving the reader/user behind.”

Writers are User Advocates

Kate explained that folks in any writing role, but especially user content (e.g., documentation, instructions, help text, user blogs, etc.), should be user advocates:

• Don’t “document around” something (i.e., rely on extensive documentation to cover up poor user design)
• Ask why
• See across features
• Use user language, rather than internal jargon
• Think about tasks (i.e., acknowledge that you’re helping people to do things, rather than documenting an interface)
• Reflect what users want to do, not the technology being used and not the underlying internal structure

Those last two points really struck home for me…

Back in 2010, we launched a new network analytics product, and it had a dashboard-like user interface. A major challenge for the marketing team was getting our sales team trained up to demonstrate the product in a meaningful and effective way. For example, what we wanted the account teams to do was take the demo audience on a journey through the network data as a means of answering important questions – the interface itself was just a tool, and its features only mattered as ways of accessing and manipulating the rich network information. What we didn’t want was for people to ‘demo the interface’; that is, to say things like, “And I can resize the window by doing this, and if I click here then I get a menu, and I can toggle the bar chart here…” While true, of course, none of that actually shows how the product itself lets you find answers quickly. To address this issue, I wrote demo scripts that showed a user journey, in which a user started with a question and embarked on a path of discovery.

And, regarding the second point, there’s a perpetual battle between the forces of outside-in, and the forces of inside-out. Kate is making the point that describing the internal structure of something (the “technical underpants”, in her words) doesn’t help your user to achieve his or her task. In my world (product marketing), this risks manifesting either as feature descriptions that, while accurate, fail to explain what’s actually in it for the user, or licensing structures that are proposed out of convenience based on our internal technology.

“Describing the internal structure of something (the “technical underpants”, in her words) doesn’t help your user to achieve his or her task.”

Brand Perception and Cohesive Experiences

Kate said it very plainly: “every channel reflects the brand.”

From your website, to your product, to your packaging, to your advertising, to your documentation…every part of the user experience can build or damage your brand. A brand is like a person: it has a personality, it evokes feelings (for better or for worse) in others, and it can behave differently in different contexts – but it should still feel like the same person. Kate used Slack and Mailchimp as positive examples, citing such elements as using contractions in language, to having funny loading messages and imagery.

Similarly, documentation contributes to brand perception: they have a voice and convey a personality; they can be aligned or misaligned with the brand; and they can contribute to a perception of simplicity or complexity.

Kate called special attention to this last point: “You can have a very clean product, a very task-focused product, and people look at it and say ‘yeah, I get that, I know how to use it’, and they look at your docs and it’s a 400 page user guide. That’s gonna undermine your credibility.”

And to those who think that’s bunk, remember that docs can be assessed as part of due diligence during the purchase process.

That said, user documentation is not marketing material. While documents should reinforce branding, they shouldn’t have a sales tone; “The reader doesn’t want to be convinced to buy it – they’re already using it.”

That said, user documentation is not marketing material. While documents should reinforce branding, they shouldn’t have a sales tone; “The reader doesn’t want to be convinced to buy it – they’re already using it.”

Remember, someone is reading the docs because they are trying to do something (a recurring theme in Kate’s session!), so a sales message would be infuriating.

At this point, I shared with the group an experience from my own past (I might be the only marketing person in the group, for all I know, so maybe the perspective is useful):

A number of years ago I opened up some of our user documentation and found that the first few pages were a clumsily executed marketing message. I was appalled. First, I instinctively agree with what Kate said about sales and marketing messages in user documentation: neither the time nor the place. Second, the messaging was horribly outdated. In tech, a couple of years can make a world of difference, and in this case the content was talking about problems that had, by this point in time, largely ceased to exist. Since I had no idea that marketing content was being co-opted into our user documentation, I’d never known to check the docs…so by the time I came across it, the message was downright contradictory to our current message. I recognize that the content had been added with the best of intentions, but it was appalling (and potentially damaging) nonetheless.

Thou Shalt…

And now we’re onto the lightning round, the straightforward edicts of user experience and documentation…

ROT is Bad – There is no such thing as neutral content: it either helps or impedes the user. Consequently, everything must have a reason to exist (another recurring theme in the session…and one of my own heart). Support user goals – “Help people do the things important to them.” – by providing focus and flow.

And here’s one that might be controversial: let the user needs and experience drive the level of detail in the documentation. What do they know already? You should write to help/empower the typical user, not every conceivable user (i.e., ones with literally zero experience with any technology ever).

And another one for the controversy pile: docs are not a product inventory, and don’t exist to validate some developer’s efforts.

Docs should (say it with me) help your users to do things.

Micro-ROT is a (Bad) Thing – For instance, you don’t need to break down all 20 steps in a process and treat them all equally. For a better user experience, separate into macro-chunks (e.g., steps 1-3 might be in a “Getting Started”, 4-8 could be “Personalizing your Interface”, and so on).

Not all the _____ – …in which _____ can be any of:

• Steps (see Micro-ROT)
• Things: learn what is important to your users (e.g., what’s done urgently? frequently?) and make that information easy to find and follow
• Ways: choose the best way to accomplish something, and have some rationale for that choice (in case you’re challenged later); “Don’t let the other ways get in the way of the best way”
• People: in Kate’s words, “Your audience is someone, not everyone. There is someone who is a representative user. When we write to the lowest common denominator, we do a disservice to the primary user.” Kate added that you need credible information about who they are, and who they aren’t.

“Your audience is someone, not everyone. There is someone who is a representative user. When we write to the lowest common denominator, we do a disservice to the primary user.”

Geeks are People, Too – Documentation can be personable and approachable/accessible without undermining credibility. Remove needless complexity…without oversimplifying. And give them some good design; keep in mind that user expectations are being set increasingly high by consumer products (e.g., Nest, FitBit, Apple TV, etc.). Good businesses recognize this, and…

Find Inspiration Everywhere – Go outside of your product domain, look at consumer products…but serve your users.

Key Take-Aways

From my perspective, a few things stood out:

• Many of the problems Kate identified stem from an inside-out mentality, and the solutions are all outside-in; that is, understand your users and do what’s best for them, which brings me to…
• Documentation is primarily about helping people quickly and effectively (and correctly) achieve some desired result. Documenting features, describing internals, and other things must not get in the way
• Nothing is neutral: content either contributes or harms
• Think holistically: user experience != user interface…there are many ways in which a user experiences your brand, product, technology, etc. A holistic approach is required.

My thanks to Kate, to Communitech, and to the folks who braved the icy conditions to make the evening a success!