Writing User-Centered Documentation, or, My Best Days as a Technical Writer

by Tom Johnson on Jun 21, 2012
categories: findability

The other day I had a discussion with a quality assurance (QA) lead that made me think about a time a few years ago that I consider my "best days as a technical writer," if such a thing exists. It was a time when I was in a much better writing flow.

In our discussion, the QA lead explained that he recently attended scrum master training (part of agile methodology). The scrum trainer emphasized the importance of having these three roles on any project team:

• Business analyst: Relays requirements and goals for the business department. These requirements are what the company wants users to do through the application.
• Functional analyst: Relays desired functionality from the customer. These requirements are what the customer wants the application to do, independent of the company's goals.
• Technical analyst: Finds compromises between requirements from the business department and customer, letting both know what is technically possible given the constraints of the project.

I don't know how accurate I am in characterizing these roles, but I'm moving towards a larger point.

What We Lack

In our organization, we don't use these same terms. We have a "product owner," "solutions manager," and "project manager." Their roles don't exactly align with the three analyst roles described above, but in some ways they do. The product owner relays the company's goals and needs with the product. The solutions manager interfaces with the product owner and oversees the strategic direction of the project. The project manager works as the tactician, working to complete requirements, plan sprints, and coordinate team assignments and overcome challenges.

What we lack, the QA lead explained, is the functional analyst -- the person who can represent the end-user's perspective, someone who interacts enough with end users that he or she knows all their pain points, frustrations, successes, and experiences with the application, and who can then inform the team about these user experiences.

Living in the End-User Space

The time when I lived more in the end-user space is when I found my best rhythm and flow as a technical writer. I wrote about this in a series of posts titled From Overlooked to Center Stage.  Basically, several years ago, when I was a new technical writer in our organization, I was dedicated to one product. I played many roles with that product: I wrote documentation, I provided support, I trained users on the product, did testing, created marketing materials, and even did some ad-hoc usability.

When I did all of this for the product, I became a subject matter expert, and I often knew more about how the product worked and what users wanted than almost anyone else on the team. I logged a ton of bugs and enhancement requests, I participated in design reviews, iteration planning, and presentations to senior leaders. I was a main go-to person for the application, and it felt great to possess so much knowledge and be an integral player on the team.

Lately  I've been reading The Insider's Guide to Technical Writing, by Krista Van Laan. So far it's lively and right on target. What I find especially relevant is Krista's emphasis on user interaction. Krista writes,

It's not uncommon for product designers and developers to get so caught up in how to make a product do something, that they forget why that functionality is needed. They can lose sight of the needs of the real person who may be depending on that product to perform a task fundamental to her job's success, safety, or convenience. (p. 14)

In other words, the people in companies that are supposed to be building tools and services for end users often forget those end users. They get lost in creating requirements documents, interfacing with project stakeholders, planning iterations, fixing bugs, and such. Very little time is spent, if any at all, interacting with actual end users.

Krista goes on to note what happens when you, as a technical writer, start speaking up and connecting various groups together:

An unexpected aspect of being a technical writer is that it puts you in a position (sometimes against your will) of "stirring the post" and initiating changes in product appearance, product function, and sometimes even how and to whom a product is marketed. How does this happen?

Well, it's a funny thing, but when a technical writer starts asking questions about a product, people start looking at it and thinking about it in ways they didn't before. And when a technical writer brings people together from different departments who might not normally talk with each other, there can be constructive dialog that otherwise would not have occurred. It can be very exciting to sit back at a lively meeting and realize you provided the spark that ignited all this exchange of ideas. One of a technical writer's most important functions is to spark discovery -- sometimes in the most unlikely places. (p.14)

In other words, when the technical writer contributes perspectives and research from various groups, these perspectives spark important and often unanticipated discussions among the project team. Whether you're bringing together users from different departments, or bringing together project leaders with end users, the resulting interactions can spark quite an innovative fire.

Changing Tides

Eventually, the situation at my work changed. Given the growing number of users, after a while someone decided we needed a dedicated support person for the application. I already created a lot of video tutorials, so I didn't need to deliver regular training. The product hit a dark phase with the budget, where it stopped changing regularly and soon had just one developer. Development efforts focused on fixing bugs rather than moving forward with major functionality and interface changes. Our department underwent a major reorganization, and our group of tech writers switched from a project-embedded model to a centralized model. Suddenly we all started working next to each other rather than our project teams.

It was great being next to other writers, and the point of the reorganization was to share our services to the whole organization rather with to a specific group. But serving the whole organization meant that we never became so integrated with any one product that we played more roles than technical writer. No more support, no more QA, no more key player in design meetings. We pretty much became a specialist for help materials only.

I was a lot happier when I was more integrated with end users. I could really go in depth with the product. Their questions forced me to find answers. The more questions, the more answers I rounded up. I became more than a peripheral player. I felt like my presence mattered on the team, and I loved the knowledge and experience I received from interacting with users. I was the connection point between the users and the team, and I could speak on behalf of the users. I almost always participated in project meetings because I could represent the user perspective, which most everyone agreed was critical.

Returning to That Role

Today, my isolation from project teams makes me much less available for training, support, and other ad-hoc opportunities to relay the end-user's perspective. I have pondered about potentially returning to a model where I'm more embedded with project teams (see my post The Proximity Problem for Technical Writers). However, embedding with the project team isn't the right direction either. I want to become more integrated and embedded with end users. Being a user champion doesn't require me to sit next to developers and other project managers. In fact, attending fewer project meetings might be a good idea, because I wouldn't be so impatient with users when they "don't get it."

Here are several techniques one might adopt to become more integrated and connected with user feedback and user perspectives:

You could review user feedback daily. In our organization, user feedback comes in via e-mail, forums, social media, and blog comments. It can be easy to ignore this feedback, but in reality, this feedback should drive documentation topics. These are the "red lines" that Philip Hodgson mentions in his insightful article, Help! What The Beatles can teach us about writing support material. Your could set aside an hour or so each day to review this user feedback.

You could relay user feedback in daily scrums. You may not get invited to project design meetings or prototype reviews (because most project leaders don't really understand the tech writer's role). But nearly everyone of us is expected to attend a scrum meeting. Rather than report that you're "writing documentation," instead relay trends in feedback from users. You can use this opportunity to communicate that you're the voice of the user.

You could connect "known limitations" in the application to JIRA items. In my help topics, I always include a topic called Known Limitations. In my Known Limitations page, I explain all the things that we know the product can't do (or which users frequently ask or complain about). It's my way of being transparent and explicit about all the application's shortcomings. Rather than just leaving this a topic in the help, you could connect each of the known limitations to items in JIRA (or whatever project/issue tracking system you use).

You could add an "Ask a Question" button in the documentation. Many of our users ask questions in our forums, but I can also solicit feedback by adding an "Ask a Question" or "Submit Feedback" button in the  documentation pages (here's a sample). Since most people turn to help for questions, this may be an easy way to probe what those questions are. The more questions you get from users, the more answers you dig up. The more answers, the more knowledge you accrue. The more knowledge, the better your ability to represent the user and the product.

For more tips, see my post, 10 Ways to Gather Feedback from End Users.

The Main Point

All of these techniques are good ideas, but they are subordinate to a larger direction: writing from an end-user perspective rather than a product perspective. Today, as I was sorting through user feedback in the forums, trying to understand it and organize it and make sense of it all, I started making notes and thinking about where and how I would integrate all of this feedback into the documentation. That's when I realized something. I had made a shift from writing product-centered documentation to user-centered documentation.

With product-centered documentation, you make your way through the application, screen by screen sometimes as you describe all the main workflows, tasks, features, and functions. The product is the starting point.

In contrast, with user-centered documentation, the user is your starting point. You write the documentation by making your way through user feedback, thread by thread, e-mail by e-mail, addressing all the main concerns, questions, and pain points that users are having.

This shift is critical to writing help. I admit that in the early stages of a product, when you don't have access to user feedback, writing user-centered documentation is more challenging. But why couldn't immerse yourself  ethnographically in the environment of your users, getting to know their business needs and goals, their frustrations and successes. Once you understand the user, you will be much more inclined to anticipate their experiences with the application.

It's not that hard to interact with end users. Phone calls, in-person interviews, e-mail questions and answers -- one could find a way. The problem is that it puts us a bit out of our comfort zones. It's so much easier to sit in little cubes and work quietly at our computers.

This leads me to another memory during my best day as a technical writer. When I worked in that department I described earlier, where I was dedicated to one product only, a project leader I worked with had a saying that would run across his computer while it was in screen-saver mode: "NIHITO." It stood for Nothing important happens in the office. It's true for documentation just as much as for project management.

Next: 1.2 New series: User-centered documentation