What I’ve Learned So Far

A good tech writer must be curious, love technology, and have the ability to learn quickly.

In other words: We head straight to the deep end and dive right in.

Expanding Past the Obvious Observation

That’s also true for most of the other roles in a tech company. But writers have the need to describe this stuff, to ask a lot of questions, and to answer questions from our customers (often before they’re asked).

At the moment, I’m juggling the need to answer specific questions (support) and the need to explain larger concepts (documentation). I want the UI to be good enough to answer the simple process questions, and it often does. Plus, users aren’t afraid to click buttons and just try things. They might have been hesitant to do that when I started as a writer (and maybe not even then), but we can assume a reasonable degree of familiarity now.

If the wrong button will delete all of their data…well, I’m guessing that while they might read this warning in the documentation before they use the product, it’s much more likely that they’ll discover it by pushing that button to see what happens. And even if “delete their data” is an extreme case, I’ve been surprised by annoying or work-destroying commands too many times to count. If you’re a writer, how many times have you clicked something to find that all of your text is now right-justified cyan H1 headings in wingding font?

So Why Do We Need a Tech Writer?

I work for a company has developed a data analysis tool. I think it’s a great tool, but it’s not as simple as loading your data and getting immediate answers to all of your questions. (In fact, it’s designed to answer questions that you didn’t know about…but our website really covers this info much better than I can here.)

This means that our users need guidance. As a writer, I’m moving away from step-by-step procedural instructions (and that’s a topic for another post), and I’ve identified two types if info that users really need: best practices (conceptual) and reference info.

So I don’t need to spend time explaining how to load a file (I’m working with the UI designer to handle that), but I need to explain how to get your data into a state that can be loaded into the product.

Another common question is about our statistical tests: What do those results mean, anyway? This info is too complex for tooltips; in fact, it’s difficult to explain in anything less than a college course on statistics. But as a tech writer, I’ve learned to do what I can, dive in, and simplify (and hopefully not oversimplify) those concepts. By talking to a few customers, and helping with a training session, I’ve been hearing two types of questions about this feature: What do the result columns mean? And how do I act on that data?

For the first, they want a reference that explains the meaning of each column. This might be something that we can do using tooltips or other in-product documentation, but the students in the training course asked for quick reference handouts.

The second is where the longer, best practice docs are needed. This is where I need to help them figure out how to interpret the results, and where to go from there (are these final results, or do they lead to further analysis?).

Serving Customer Needs: Docs and Training

During the training course, we (the trainers) realized that the customers needed more than a lecture, slides, and a demo. They also wanted handouts, quick reference sheets that they could take notes on and use during the exercises.

So: Documentation, but limited, specific documentation. After the training course, they’d get value out of the longer best practice and more extensive reference docs on our knowledge center.

(And I’ll note that I didn’t have those quick reference sheets ready before class, but I did have the larger docs to refer to. So I was able to create something during a break. Part of my job is to make sure that we’re not surprised like that again.)

Guiding the Reader

Back to the best practice docs. First of all: Those things are difficult to write. More correctly: They’re difficult to plan, research, and organize. First, I need to learn what the users need to know. And “What do our users need to know?” is a big, open-ended question.

Something like “How do you analyze your data?” is a bit better, but it’s still pretty broad. At that high level, I can provide some guidance, but it sets up what Tom Johnson calls a narrative workflow topic.

At a previous company, I worked with a writer who developed a set of narrative workflows for our API reference. I think we called them “user scenarios” or something like that, but it’s the same concept. The API writer created a couple of fictional users and their use cases, and then created a set of scenarios about their work processes. These would introduce new users to the API functionality, and would have links to the appropriate reference pages. Unfortunately, we ran into opposition from project leads who wanted something “now” rather than “new,” and they felt that too much documentation would make the API seem complex.

So sometimes good ideas aren’t enough to win people over. In that case, we ran into timing issues (which turned out to be false once the project slipped a few times), and we weren’t able to convince the project leads that the narrative docs would help users learn to use the API better than a set of bare bones API reference topics.

There should be ways for advanced users to skip past those narratives (or never see them) and go straight to the reference pages. We were building signposts in the docs to direct users to the information appropriate to their experience level, and I think those narrative workflows would have been a great way to start learning about the API.

Back to the Present…

Even though we didn’t get a chance to complete that project, I still like the idea of narrative workflows/user scenarios. I’ve received feedback from customers that they need more guidance from the documentation: Not just for the product, but for the documentation itself. Even though I believe in the every page is page one philosophy of tech writing, some users need very explicit instructions about where to go next. And while “Related topics” lists are useful, readers often want to know the one specific topic that they should read next, and not look at a link of 3-5 topics that all sound reasonably useful.

Those are the users that will get value from the narratives. Even though they’re wordy, I think they’re more user friendly than a bullet list of tasks. At least, that’s my theory. I need to put it into practice now and measure the results. I’ll keep you updated.