I wonder if there’s a tech writer out there—in the software industry, anyway—who would argue that being involved in the design stages of a project is a bad thing.

This theme comes up time and again among our User Education team members. Yesterday, one of us gave a presentation to our community of practice about usable design, what makes something usable, and how tech writers can contribute. She suggested we come up with some metrics that help us demonstrate how our contribution to usable design increases user productivity and lowers cost.

As part of her illustration, she showed a chart about the more and more expensive it gets to fix a bug from the requirements stage through to the maintenance stage.

An idea came to mind, and I shared it with the team, that one of the things that we can use some hard numbers with is determining how many steps it takes to complete a task. The presenter had used an example to show how a process that she would have expected to take four steps instead took twelve. If we can analyze designs and determine how many steps it takes to complete associated tasks, we can tell the project team, “That’s going to be hard to explain. That process will take ten steps (or fourteen, or twenty). And when a user sees a procedure with that many steps, the first thought is ‘This is going to be hard,’ probably followed up with ‘I hope I do it right.’ Confidence goes into a nosedive.”

› Continue reading…

Bookmark It

Hide Sites

In my initial conversation with the manager of Project Pinnacle, we decided on a set of role-based quick reference guides as the documentation for the application.

I ended up with about five weeks to complete these guides in the midst of other projects. After a demo of the application given by the lead tester, I sent the manager an outline of each guide. He didn’t get back to me right away, so I started writing the guides while using a test version of the application.

The guides’ structure was pretty simple. On the first page, I included a screenshot with callouts that explain the navigation structure of the application: header, subheader, tabs, links, buttons, and so on. The hope is that this would reduce the amount of instructions needed by covering the basics together. After basic navigation, I covered the main tasks for the role in question.

› Continue reading…

Bookmark It

Hide Sites

One of my fellow members of the Intermountain Chapter of STC is a major proponent of tech writers having project management skills. Planning is one of these skills.

I’ve thought for years that I’m not interested in becoming a project manager because the only writing they do is project plans. That kind of writing has held no appeal for me, and that’s probably why I’ve never seriously considered writing documentation plans before now.

Tom Johnson recently wrote about how the user education team in our organization is introducing a user education plan as part of the standard planning process for projects. He explains that he has come to support having this plan to fill out mainly because it will help him manage his time so he won’t be overwhelmed by work for various projects and then become unable to deliver quality products.

For me, the attraction of a user education planning document is to speak project managers’ language. They think in terms of budget, milestones, deadlines, requirements, and risks. A good user education or documentation plan will address these areas.

› Continue reading…

Bookmark It

Hide Sites

I was hired by my current employer to provide documentation on a large and complex Web application to be used internally. After the main development phases ended, this project moved into maintenance mode. Developers, testers, and other team members were moved onto other projects.

Over time, other applications that we developed also moved into maintenance. Over the last several months, we brought in some developers and testers to fix bugs in and add small enhancements to these maintained apps. We also had a business analyst come on board to replace our previous one. He already knew a lot about some of our systems because he had worked on the original requirements.

The interesting thing about these developments is that I became one of the experts on our applications. When these new developers and testers came on, I was asked to give them an orientation on the applications. Since then, when they have questions, many of them have asked me.

Being the expert has led to a couple of small expansions to my role.

› Continue reading…

Bookmark It

Hide Sites

In our ongoing department reorganization, we technical writers are experiencing some angst as we carve out a desirable place for ourselves. However, as we’ve talked about it as a community of practice (no longer as an organized team with our own manager), I think we’re coming to an agreement that now is the time to make things happen—to strike, as Tom likes to say.

After the initial, high-level reorganization, Tom and I are in the same division, so we’ve discussed a plan for taking a more prominent place in project managers’ and interaction designers’ consciousness. This is the key for us because the PMs are the ones to include us in their project plans and budgets, and we would be working with designers to decide on user education approaches and contribute to the design itself.

Finding Tech Comm’s Place in the Family

After Tom’s blog post about our meeting with an interaction design manager, I asked him about his point of view and his readers’ reactions to the post. We discussed getting involved in projects early and contributing to user interface text. We talked more about this in our community meeting this week. Again, we’re looking to make sure that the people who make the decisions give us a rightful place at the table.

We also talked about many designers’ “holy grail” of creating products so intuitive that no documentation is needed. Tom reminded me and then the group of an important point I had forgotten. An interaction designer once said something like this to me, and I had passed it on to the team: “Saying that ‘if the interaction designer does his job right, the product doesn’t need help’ is like saying ‘if the developer does his job right, the product doesn’t need QA.’”

› Continue reading…

Bookmark It

Hide Sites

I knew from the email subject line that I wasn’t going to like what was in the message.

The subject contained the name of an application, then two frightening words: “help sheets.”

I’ve found that outside the tech comm profession, people tend to throw around terms like “help” and “tips” without really thinking about what they mean. That’s why I felt a bit of dread as I opened this particular email.

The Rogue Documents

Looking for feedback, the product manager had forwarded two Word documents from an instructor who teaches this particular application as part of a week-long training for office staff. The instructor had documented a couple of end-to-end processes that weren’t strung together like that in the help.

Let’s just say that these documents weren’t done by a professional tech writer. I didn’t even get down to giving feedback on a content level; a subject-matter expert did some of that. Instead, I was concerned that by giving these documents to the class members, we were providing an inconsistent and less-than-professional experience.

I was also concerned because these documents’ pages were numbered 35 through 41. So what else was there that we didn’t know about? How much effort was being duplicated? Since it’s my full-time job to create such materials, I would have preferred if the instructors let us know about the need and asked me to fill it. Frankly, it felt a bit threatening, as if I thought my job was in danger. I considered this “rogue,” or unofficial, documentation.

The Idea

I ignored this email until the next day. Then, however, I decided to change my stance. I realized this was an opportunity, not a slap in the face.

› Continue reading…

Bookmark It

Hide Sites

This month we’re transitioning from an old custom document generation application to a new one. Having been the person responsible for training a small group of users, I spent much of yesterday with the person upon whom falls many of the weekly tasks. The project team and our customers wanted to be sure that she’s ready to go when we’re live with the new application and the old one is turned off. (The old one is connected to a legacy database that will be retired soon, so it won’t be available as a backup for very long.)

As we went through the document generation process, this particular user—let’s call her Melissa—let me know where she wasn’t clear on one thing or another. Particularly, she wasn’t clear on what were the exact differences between each of the three screens that the process involves. As we got to the end and Melissa still seemed a little fuzzy, I asked, “Would it be helpful to have a one-page guide that walks through the three basic steps?”

Now, there is a help system. I even have a topic that covers this process from start to finish, involving about ten main steps. However, I could suddenly visualize a page where I matched three steps (with a few substeps each) with the three screens. But the approach here was to give the instructions in their most basic form and leave out a bunch of the details.

› Continue reading…

Bookmark It

Hide Sites

Email takes too much of my time. Not because I drop everything I’m doing to read an email whenever it arrives, but because when I write one, I review it at least once before sending it.

I’m almost obsessive and/or compulsive about this. I have to read over the email to make sure I said what I wanted to say and didn’t say anything I didn’t intend. I need to be certain my message wouldn’t hurt anyone’s feelings (if feelings are at stake). Instead of being a convenience, email turns into a big project.

Sometimes, if my emotions are involved in the email, I feel like a jerk even if I reviewed the email multiple times before sending. I feel horrible for having asserted my own point of view.

Why?

When I was about to graduate from high school, I finally decided that one of the keys to happiness was to stop caring what other people thought about me. I wished I’d have thought of that a couple of years earlier. But this was a liberating epiphany for me. The second part of this discovery (and perhaps just as important) was the realization that it was conceited of me to think that other people thought anything about me at all, let alone thought negative things about me.

I thought I didn’t care anymore about what others think about me, and I’ve learned I was wrong. Or at least that it didn’t last.

› Continue reading…

Bookmark It

Hide Sites

A local sales writer who was looking to get into technical writing asked me a few questions to help him get an accurate picture of what he needed to be successful. One of his questions was “What are some character traits of a successful technical writer?”

That’s kind of a tough question because tech writers have as many different personalities as any other group. But the question is about character traits. I believe it was Dr. Taylor Hartman, author of The Color Code, who said that you’re born with a personality, and what you do with it is your character. If I go by this definition, character traits are things that you choose to do, habits that you develop. I’m going with this definition because I don’t think any certain personality makes someone a more successful technical communicator; it’s those choices you make and the habits and skills you develop that determine your success.

Let’s back up a little bit more, though. What constitutes a successful technical communicator? The usual judgment of success is how much money you make, but I think that’s a different discussion. Additionally, certain successes are something that you have power to accomplish yourself, not something you’re dependent on others for. Success in technical writing is one of these things.

A successful technical communicator is one, I believe, who understands both the audience and the subject matter, clearly communicates what the audience needs to know when they need to know it, and puts the content where the audience will get it. Note that this definition means success isn’t dependent on receiving recognition for outstanding publications or a certain salary or hourly wage. It’s not even dependent on increasing the organization’s profits, because not all technical writers work for commercial entities (take me, for example).

› Continue reading…

Bookmark It

Hide Sites

Having recently been included in release readiness meetings, I’ve had a few more items on my weekly calendar. Before that was the communication vs. programming problem we worked through.

One of the project managers I work with came to my desk a couple of weeks ago and told me that he had just come out of a two-hour meeting that I probably should have been in. Apparently one of the primary users of one application can mostly navigate the complex set of business rules that the system supports and do what he needs to do, but he’s missing some of the nuances. So the manager said that the leadership team discussed possibly making some changes in the next few months, but they’d need me to take these business rules and boil them down to simple a cause-and-effect document. “I’ll make sure to include you in future conversations about this,” he said.

› Continue reading…

Bookmark It

Hide Sites