I just started on a new project this month. Taking the lead from Karen Mulholland‘s reporting on her Tribal Knowledge Project, I’m going to blog about how it goes.

In order to protect the innocent, or the guilty as the case may be, I’ll call it “Project Pinnacle.”

Tom, one of my User Education colleagues, was approached by a project manager he had worked with before to work on Project Pinnacle, but he didn’t have the bandwidth to take on a new documentation project. Tom asked if I could do it, so I asked him about the timeline and what deliverables were needed.

He told me a bit about it, and I decided I could take on the project. Tom forwarded me some information, including a link to a test version of the Pinnacle application and test credentials. When he let the PM know that I was picking up the project, Tom sent me an email explaining what he knew about the project to that point. Pinnacle would be used at various locations worldwide for organizing workers and their shifts and also scheduling visitors.

Tom and the PM had talked about making a set of role-based quick reference guides. He said that the application didn’t have a help link and needed one. I took this to mean that online help was an expected deliverable for the project, and I was a bit uneasy about that, especially since Tom indicated that the timeline was pretty short.

I decided that rather than jump in and start developing material, I needed to talk to the PM. I had a hard time getting a hold of him; I tried instant messaging, phone calls, and even stopping by his desk. In the meantime, the quality assurance lead had offered to give me a demo of the application, so I took him up on that.

Fortunately, Tom sits near the PM and let him know I was looking for him. He IMed me to find a good time and then called me on the phone.

My main questions were about schedule and scope, since I needed to make sure we would have the same expectations.

The PM told me that Pinnacle would be piloted in Twin Falls, Idaho five or six weeks out. He was still working out details. To my excitement, he asked if I was interested in joining him and the product manager the last two days of the week, which are the days of the heaviest traffic in that location, to observe users and see how they like to get help.

Heck yeah I’m interested, since usability is one of my interests and I also want to test out the guides I will have created by that time.

I asked about the deliverables for this pilot. We agreed on a set of quick reference guides, but I expressed my reluctance to do an online help file because I didn’t think the user demographic prefers that (and I’m not sure what demographic does prefer online help files). I was relieved when the PM said that he didn’t think a help system is a good fit for this project, either. Our users will mainly be people between the ages of 55 and 75 or 80.

So at least for the first stage, I’ll be creating four quick reference guides to be ready, at least in draft form, for the pilot in a few weeks. I’m looking forward to watching the users and seeing how well the guides measure up. It will be disappointing if what I put together doesn’t prove to be what they want and need, but I’d rather go on-site and find that out rather than prepare and distribute materials that don’t do the job.

I would have liked to be brought onto the project earlier so I had more time to work in. This is one of the reasons I want to write about how things go—it will be a way to reflect on and analyze what I’m doing and see if it’s working. Come along for the ride and feel free to offer advice on the way.

Bookmark It

Hide Sites

When deadlines are hurtling toward you with all the leniency of a runaway dump truck and you realize that you have to sacrifice something in your user education project, what do you choose to drop?

Sometimes you can even see the problem coming when you start the project. Not everything will make it, so you have to let some things fall by the wayside. Maybe it’s one of the rounds of reviews. Maybe it’s the troubleshooting section or the index. Maybe it’s the screenshots or fully colored and designed diagrams.

I confess that when I need to get the job done and I’m pushing myself to write, I feel the temptation to make the worst shortcut of all.

I’m tempted to make assumptions and trust them instead of getting off my rear or picking up the phone and asking someone, such a subject-matter expert or a user.

This is the shortcut that tech communicators can least afford to take.

Why?

› 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

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

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

I’ve been asked what the biggest surprise was for me when I went full-time into the field of technical communication following university graduation. Honestly, not a lot surprised me; I knew how to write procedures, gather information, and use Web, print, and graphics tools. I had even worked in a company environment during a short contract period following my freshman year of college.

So what was the surprise?

Basically that on a significantly sized software development team, no one really knew how to work with a technical writer. So it was up to me to educate them. Problem was, I didn’t know how they were supposed to incorporate me into their team either.

When I worked in that contract position I mentioned, it was on a team of writers and editors. Because we were dealing with content for a website, we interacted with a couple of database administrators, but that was about it. Most of our interactions were with each other and our team lead’s manager.

› Continue reading…

Bookmark It

Hide Sites

Still somewhat surprised that Vanessa, the project manager, had labeled him a major player in solving the customer’s problems, Henry projected his improved diagram onto the screen. Everyone looked at Vanessa.

“Henry, will you explain the diagram, and then we can go through each situation and find out whether the right things are happening.”

Henry hadn’t expected to guide the discussion, but he talked through the diagram. Then he began going through each relationship and explaining the effects of the relationship on the reports that the users were generating using the software.

As they went, the customer identified where things were happening correctly and where something needed to change. Vanessa kept track of action items, and since they uncovered a couple of inaccuracies, Henry took note of where he needed to make changes. Vanessa then asked Henry to create a version of the diagram that represented what should be happening in the software as if it already was. The development team could take that version and begin creating and assigning tasks.

When the meeting was over, Henry couldn’t help but experience some relief. The spotlight had been moved elsewhere. His original documentation on the software had contained a couple of errors, and he would fix them, of course. It was possible that the number of questions and problems coming back to the customer stemmed from those errors. But this possible communication problem had exposed a programming problem. And Henry, being the professional communicator on the team, had taken the task of communicating to the customer how the software currently worked, and doing it clearly enough that the customer could make informed decisions. So communication had been the first step to solving the programming problem.

› Continue reading…

Bookmark It

Hide Sites

Once again, Henry met with the project leadership; only this time, he was the star of the show. In the last meeting, he had taken the assignment to diagram the relationships that were currently possible to set between two types of objects in the software, as well as the downstream effects of those settings. He had to represent four criteria in a two-dimensional diagram but had a hard time thinking in four dimensions at first.

After some thought and experimenting, he accounted for all four types of variables by combining two of the criteria into one axis, putting the third across the other axis, and explaining the effects at the intersection of row and column. It didn’t look amazing, but it would do the job.

A little timid, Henry projected his laptop screen onto the conference room wall. He glanced around and saw a couple of confused looks.

› Continue reading…

Bookmark It

Hide Sites

Henry opened up a PDF on his laptop and went to page 27. The meeting continued around him as he scanned the text of the procedure he’d written 18 months before so he could verify some of the information that had been distributed.

“One way to look at this is that we want to prevent our customer from getting these phone calls all the time—or at all,” said Vanessa, the project manager. “What’s the first step?”

George, the business analyst, lifted a hand. “Well, since he keeps getting asked why people are or aren’t seeing this or that in the reports, I think it’s a data problem. We need to start there.”

“Or it’s a training problem,” said Melanie, the lead of the quality assurance team. She looked at Henry. “If there’s a data problem, maybe the users don’t understand how to set the data up correctly.”

› Continue reading…

Bookmark It

Hide Sites

Sometimes, the Agile software development methodology seems like it could be renamed the “Fly by the Seat of Your Pants” methodology. But really, it means that you need a somewhat different set of project management skills for your documentation. I could certainly improve in these skills, but here are a few I rely on in an Agile environment.

Skill 1: Topic-Based Writing

Before I describe this one, I need to point out that yes, writing isn’t exactly planning; writing is what a technical writer does after planning. Writing is a rubber-meets-the-road activity.

True, but the project management applies in the way that you plan to write. I heard it said once that DITA is perfect for Agile environments because the way writers chunk information in that scheme allows that information to be dispensed from a single source into whatever output happens to be needed at a particular time. In short, it allows writers to quickly respond.

If I could substitute “topic-based writing” for “DITA” here, I would add that another great benefit is that writing in small topics allows you to keep pace with development and to release documentation in step with the application updates. Small topics give you less work to do in the iterations or sprints and enable you to mark your progress more regularly. So plan to write small in general and then adapt as needed.

› Continue reading…

Bookmark It

Hide Sites