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

Related posts (auto-generated):

1. The Technical Communicator as Project Manager
2. Quick Reference Guide Webinar from Yours Truly on February 10
3. Offering a Menu of Tech Comm Deliverables
4. Five Skills for Managing Documentation Projects in an Agile Environment
5. Why a User Education Plan Will Make Project Managers Love You

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?

Assumptions lead to inaccuracies. Unverified information may cause misunderstanding, misuse, and even legal prosecution against the organization that publishes said information. When our job is to communicate clearly and accurately, leaving the door open for inaccurate material should be a choice that fills us with distaste and horror. But we may do it anyway sometimes if we’re not paying enough attention.

Take this shortcut and watch the frustration—or worse, much worse—ensue.

Making assumptions is not a shortcut to a successful product; it’s just a shortcut to getting things done faster.

One area where this applies is getting context for users’ tasks. It’s easiest to just document a set of steps, but it can be helpful for users to include some context around when they would perform that task. Maybe you know part of the story but not all. So because of a time crunch, you want to fill in the gaps in your knowledge with inferences that make sense to you.

Don’t do it. Don’t give in. If the most conviction you can muster is “I think . . .” then go ask someone who knows. It needs to be “I know” for you too. Your documents will be better.

If your documents are clear and accurate, everything else is probably forgivable. What do you think?

What do you sacrifice in your projects when you’re short on time? Have you sacrificed something and regretted it later?

Bookmark It

Hide Sites

Related posts (auto-generated):

1. Seven Reasons Your Company Needs a Technical Communicator

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.

A certain project manager recently switched to overseeing projects I work on; he came from a project for which one of my colleagues, Paul, submitted this user education plan. The manager liked it and is in favor of seeing it happen more. Derek, another colleague, submitted one for a new big project, and he said the look in the manager’s face could be described as “enamored.” Even though the new process hasn’t been rolled out to the department, using this user education plan is making long strides in getting project manager support for user education.

This is the crux for me. The project managers are the gatekeepers for project priorities and budgets as far as individual contributors are concerned. If the manager doesn’t think user education is a priority, he won’t budget it into the project. If he doesn’t understand user education, he won’t think it’s a priority.

Speaking of organizations in general and not just the one I work in, this widespread failure of project managers to understand the value of user education (or documentation, user assistance, or whatever you want to call it) stems from the failure of technical communicators to speak in project managers’ language.

Yes, I think the blame largely rests with us.

We like to talk in our tech comm club about our value and bemoan our lack of prominent place in project teams if such is the case. We discuss the importance of showing value. But I think a lot of our problems come from not having figured out concrete ways to do this.

Another important skill for tech writers—for any communicator—is knowing our audience and choosing our mode of communication and message accordingly. But we fail to consider the project manager audience that we need to appeal to in order to get user education the place it deserves, we have probably failed to properly communicate.

Performing audience and project analysis up front and then providing a plan that speaks in project management terms is a significant area where we can show project managers that we’re not clerks and typists and we can’t be replaced by any Tom, Dick, or Harry off the street.

I’m optimistic about the effect that this plan template will have in our organization. Project managers I work with aren’t against user education; they sometimes merely forget to include it until later. With this kind of analysis and planning at the beginning, the tech writers position themselves to enter the project at the right time with the full support of the project manager.

If you’re already doing this, what has been your experience? Has it worked?

Bookmark It

Hide Sites

Related posts (auto-generated):

1. The Technical Communicator as Project Manager
2. Three out of Four User Education Team Members Choose Flare
3. Reviewing Projects and Deliverables as a User Education Team
4. Why Writers Should Be Involved Throughout the Project Lifecycle
5. Teaching Project Management How to Work with Technical Writers

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.’”

I’ll run that by you again:

Saying “If the interaction designer does his job right, the product doesn’t need documentation” is like saying “If the developer does his job right, the product doesn’t need quality assurance.”

Not many project managers would argue the value of QA. So why should they argue the value of technical communication?

If you boil this designer’s statement down to its basic premise, you get “The technical writer provides quality assurance for the interaction designer.”

When you think about it this way, you’ll start to get a sense of why tech comm ought to have a place in every project meeting from the design phase all the way through to the end—why we ought to be sitting at the table with the other project leads.

You Provide Quality Assurance Too

Let’s take a look at what quality assurance is all about. At least in the software development world, quality assurance engineers, more simply known as testers, exercise the software once coded to make sure it meets functional requirements. Clicking a button or link brings about an expected result. Inputting certain data returns certain other data or provides specific options. The idea of all of this is to make sure that someone using the product accomplishes certain predefined objectives.

If you’re fortunate, you work in a company that places usability testing among its priorities. In the Agile environment I work in, we don’t have much time between design and development to conduct usability testing. Any testing we could do would have to be early, probably with paper prototypes and grabbing some person at home to try them out. Usability testing, as the name suggests, tests the design.

Either way, the tech writer tests the design. We do this by making sure, as we provide documentation and training materials, that the user can accomplish predefined objectives using the design that’s provided. Yes, we may log some bugs along the way. Yes, we want the product to actually work and not return errors. But what we’re mainly concerned with is how to navigate the product’s visual elements to accomplish a task.

As we document steps, we can see when terminology doesn’t make sense or when a control is hard to locate. We can see when a task takes too many steps, includes steps with too many substeps, or has an inordinate amount of permutations of the same step. We can see inconsistencies in different parts of the product. We are the first users.

People are people, and we like simple. Some business processes or other procedures are complicated, and we may not be able to do anything about that. But we can help make sure that the products that support those procedures are as simple as possible.

Wrap-Up

Quality isn’t found solely in working code. Quality is found mainly in the experience. Technical communicators are immersed in the experience of a product because we have to understand it. We have to see it as the user sees it. As a result, we can provide quality assurance for product designs beginning in the early stages of design and development.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. A Writer's Exercise for Critiquing Design
2. An Interaction Designer Who Understands the Need for Documentation
3. Four More Reasons Your Company Needs Technical Communicators
4. Problem-Centered Design for Documentation
5. Where Usability and Documentation Meet

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.

Technical communicators often talk about demonstrating value. With that in mind, and with these things going on around the same time, I devised a theorem; let’s call it “Minson’s Theorem of Perceived Technical Writer Value”:

The number of conversations you are involved in is proportional to the value you are perceived to have.

Most people don’t like meetings. I don’t mind them if they accomplish something and don’t waste time. But meetings aren’t the only conversations I’m talking about. Sometimes a question from a manager to a developer turns into a prolonged discussion, and they decide others need to be tuned in.

This may not be limited to technical writers, but my point is that the more value you are perceived to have, the more that other team members will want to keep you informed and ask for your opinion. In one of these release readiness meetings I was invited to a week or so ago, the attendees were discussing a newly discovered complication with Winword.exe. The basic question was “What is the best way to keep the users’ experience friendly when encountering this problem?” When a couple of options had been brought forward, the project manager asked me what I thought. A little surprised that I would be asked for my opinion, I gave it. But I’ve been in charge of training the users in advance of our release, so I had an idea of which option would disrupt their work the least.

I’m sure this theorem isn’t 100% correct, or it has many corrolaries, which is why I called it a theorem. That, and it sounds slightly mathematical (I remember a bit about theorems from my days in geometry class). So if you agree or disagree with the theorem or can offer any corrolaries, please see your way to the comments form.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. Helping the Team Broaden Their View
2. A Process for Developing Regular Release Notes
3. Teaching Project Management How to Work with Technical Writers
4. Release Scrums: An Important Resource for the Agile Technical Writer
5. Five Skills for Managing Documentation Projects in an Agile Environment

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.

How I Fit the First Time Around

When I was hired as an intern by my current employer, the team was in iteration twenty-something of a big, complex software project that had significant documentation needs. They were following an Agile methodology using scrums. The business analyst who acted as my supervisor gave me a document that explained their iterative development, which involved groupings of iterations into cycles. He asked me to create stories and tasks in the tracking system the team was using and chunk my work such that I could complete tasks each iteration. The analyst would review my work each iteration and give feedback.

The development manager decided that since the online help was part of the software, the results of my iterative tasks had to be tested and passed off by the quality assurance team after the business analyst reviewed it. Since the manual was part of my work, it would go through the same process. Different team leads have held to that idea with varying strictness.

What I Learned

I found that the way UI-development user stories and tasks were broken up didn’t have a one-to-one relationship with task-based procedures or with context-sensitive help topics. As a result, it became difficult sometimes to chunk my work in ways that made sense for testing. For example, some development tasks may have had impact across multiple screens of the application, while others may have required a single sentence to be added somewhere in the help or manual (not enough work to justify a full task).

In addition, after the initial release, the team began releasing at the end of every cycle. Because designers and developers could be making changes up until code freeze, and because the users wouldn’t be seeing new docs until the release anyway, I decided that it didn’t make total sense to adhere to the iteration deadlines. It was more important to make sure my content was created, reviewed, and tested by the end of each cycle. That gave me more time to deal with changes. A hardening period before each release became very helpful for me.

Further Projects

Some of my colleagues work on a project where some aspects have been outsourced to a third party who has tried to push the code development process on documentation development—as if it were simply a matter of putting the same clothes on a different child. Only in this case, the children have completely different shapes and sizes, and what fits one has caused restriction and discomfort for the other. Documentation cycles of writing, editing, review and feedback, and publishing don’t match coding processes exactly. So they need to be allowed their own schedule to some degree.

The portfolio I work in has implemented an arrangement called micro-teams, where two Java developers and a tester work together on development tasks. This is an arrangement where it doesn’t make sense for me to be in a micro-team; I’m not always going to have something for a tester to test, and there’s only one of me in my portfolio. Therefore, my role is a support role to multiple micro-teams.

What’s It All Mean?

If you’re moving from some other field into tech comm, or graduating from college and hunting for a tech comm job, do your best to learn how to fit into your team. Talk to technical writers in different disciplines—software, medicine, science, and so on—and find out how they keep pace with their teams.

Particularly in an Agile software development environment:

1. Plan out the general length of help topics or other chunks of content.
2. Determine how long it will take to get the content through the writing and review cycle.
3. Find out whether management expects the content to be ready at the end of each iteration, as of the regular code freeze, or when the code is released.
4. Work backward to see how the documentation cycles work within that.
5. Negotiate if necessary.

If you’ve got some experience behind you, you may have some hard figures to offer (“It takes four hours of work to complete the cycle for a topic; therefore I can complete X topics in one iteration”) or at least have some anecdotal support for your preferred methods.

Different managers will react differently to your suggestions. Be ready to adapt. Fortunately, I’ve worked for project managers who weren’t interested in micromanaging my work; they were interested in the results. As long as I came up with the results on time, they didn’t worry about how many days my documentation cycle took. So they learned to trust my methods.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. A Bug-Fix Cycle at Project End Is Good for Everyone
2. Suggestions for Survival in an Agile Environment as a Technical Communicator
3. Why Writers Should Be Involved Throughout the Project Lifecycle
4. The Technical Communicator as Project Manager
5. A Process for Developing Regular Release Notes

“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.

In my experience, a diagram—a method of communication—facilitated a discussion on what needed to be improved about a family of applications and their connected wiring. Most of the current functionality was right, fortunately, or we could have been somewhat embarrassed. The developers need to make just a few minor changes so that the users get the right information in their lists and reports.

Looking back at the process, I’m not sure how I became one of the main participants in the discussion; it may have been that diagramming the applications’ current workings was considered documentation, or similar enough thereto for the tech writer to do a decent job of it. It became a sign to me, though, that it’s possible for the technical communicator to climb the evolutionary ladder from the person who just documents the product to someone who facilitates the solution of problems.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. Communication Problem or Programming Problem? (Part 2)
2. Communication Problem or Programming Problem? (Part 1)
3. A Bug-Fix Cycle at Project End Is Good for Everyone
4. Four More Reasons Your Company Needs Technical Communicators
5. "If an App Is Designed Well…"

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.

“Henry, will you talk us through your diagram here?” asked Vanessa.

So he explained the meaning of the diagram and how, using it, someone could predict what the effects would be of setting up a given relationship between the two main types of objects in the system that were causing problems for the customer. The team identified some places where Henry needed to add information, but it was accurate for the most part.

“Let me make sure I’ve got this,” Nick said. “I want to walk through an example.” He talked through his example, and with some help from the rest of the team, he correctly matched it to the intersection of one of the rows and columns.

“Very good,” said George, nodding. “I think this diagram will do the trick. Once you work those changes in, we can show it to the customer.”

“And have him tell us where things should happen differently,” added Vanessa. “I think we have it mostly right, but there are going to be some enhancement requests coming out of our conversation with the customer.” She looked around the room. “I don’t think everyone here needs to meet with the customer. Who are our major players?”

“Well, you should be there,” replied George with a smile.

“Yes, I plan to be there,” Vanessa said. “George, you ought to be there as well. You know more about the data model than anyone. Henry needs to be there too.” She looked around. “I think that will do it. I’ll set up that meeting. In the meantime, Henry, please update the diagram and send it back out to us.”

Henry nodded and disconnected his laptop from the projector as the meeting broke up. He was a little surprised to be considered a “major player” in this process. But it was probably as much a communication problem as a programming problem. Communicating the current wiring of the system accurately was essential so that the customer would have the information he needed to be able to tell them how they could relieve the problems that were occuring.

Admittedly, I was a bit nervous to show a diagram that I thought was a bit ugly to a leadership team, including a couple of business analysts, who are generally adept at creating diagrams. But after we ran through some examples as a group and the diagram held up (with some gaps needing to be filled in), the team agreed that we could move forward and talk to the customer. I asked one of the business analysts for some advice afterward for improving the appearance of the diagram, and the document turned out looking a lot cleaner.

Just as Henry was in this story, I was a bit surprised to be included in the group of key players (or whatever term the manager used) who would be talking to the customer in the next meeting. I actually was about to open my mouth and say I think I didn’t need to be there, when the program manager said I needed to be there. So I wasn’t going to argue. It was an illustration of the concept that when communication is important in a situation, a professional communicator becomes a key player.

Keep an eye out for Part 3, where we’ll see the results of the communicator being involved in a communication and programming problem.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. Communication Problem or Programming Problem? (Part 1)
2. Four More Reasons Your Company Needs Technical Communicators
3. Suggestive Selling for a Tech Comm Storefront
4. Three Ways to Get Developers to Keep You up to Speed
5. Already Getting Distanced from Some Project Teams

“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.”

“Which still makes it a data problem,” said George. “We need to identify what our software is currently doing with the data and how it feeds the reports. From there, we can determine whether the software meets all the needs and we just need to do better at educating the users. Or it’s possible that we left some things out of our data model. Maybe we didn’t understand as much as we thought we did a year and a half ago. The users may be trying to create relationships between objects in the system that we didn’t anticipate.”

“We did distribute a PDF when we released the software,” Henry added. “So we’ve told them how to set up the relationships between objects.” He glanced again at the text and then stared. Given the understanding he’d gained in the meantime, plus the content of the discussion, he found a couple of only partially true statements in the instructions.

He wondered if the problems that the customer was experiencing resulted from what amounted to inaccurate documentation.

And he didn’t want to speak up and suggest this to the group. Yet.

“Maybe what we need is more validation in the system,” said Nick, the development lead. “Documentation is fine only if the data stewards use it, and we don’t know if they are. If we put more validation in the system, then there’s less room for mistakes.”

“That would be some complex validation,” countered Theodore. He would know. Henry had had to document some of the data processes in another project where Theodore had been the database administrator, and he had done some amazing things with stored procedures and such. “It would be a lot of work to have the system analyze all the variables and give appropriate feedback. I think training is the key.”

“I think we’re getting ahead of ourselves,” Vanessa said. “Let’s start with George’s suggestion and identify what the software is doing. We need to show the customer the consequences of the relationships the users are setting up and find out how much of that is what’s supposed to happen. Who should do that?”

After some discussion, they settled on Henry as the person who would take the next step. He took the assignment to diagram the current effects of various object relationships in the system. “We’ll meet again on Thursday and use Henry’s diagram to guide our discussion. We’ll verify the accuracy, and then we’ll take it to the customer.”

As the meeting was breaking up, Henry asked George to come over. “I think these statements aren’t entirely true here.” He read them.

George’s eyes wandered as he thought about it. “I think you’re right.” They identified the correct phrasing, and Henry made a note.

“I wonder if this problem stems from this being wrong,” he said. “I could see how some of the problems the cusomer has seen could have happened because of this.”

“That may be the case,” George replied. “But I still think we’re missing something in our data model. If this procedure being wrong helped us realize that we missed something, then maybe it was a good thing.” He smiled briefly, perhaps a bit embarrassed himself. George had reviewed Henry’s documentation, so if it contained errors, it meant George had missed them too.

A little reassured, Henry returned to his desk and focused on the puzzle that was the data model.

Something like this has come up for me recently. The customer was receiving a lot of phone calls that boiled down to the same question. One phone call in particular became the proverbial last straw that spurred the customer to ask the program manager to look into the problem. In looking at my documentation, I found a couple of inaccuracies, and it’s possible that they were the direct cause of the data problem we ended up with. I haven’t verified this yet because at this point, it looks like it hardly matters (as long as I correct the inaccuracies). If my documentation led to the problem, it has led us to analyze a bigger problem that’s really at the heart of our customer’s difficulty.

The discussion has been about what needs to happen in our system vs. what is actually happening. We think the programming and the data model have fallen short in some ways; fortunately, the wiring can probably be fixed with relatively little pain. It’s a matter of making sure we know what the customer wants to happen so it will be programmed the right way.

However, it’s not just a programming problem. There’s also a communication problem to solve, and the first step was to portray our current system wiring in a way that the customer can understand and use to make decisions. I was given that assignment to put together this communication.

Stay tuned for Part 2, which will talk about the next stage.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. Technical Communication Can Require Heavy Duty Hardware
2. Four More Reasons Your Company Needs Technical Communicators
3. Technical Communicator = Perfectionist?
4. Could Technical Communication Be Entertaining?
5. "If an App Is Designed Well…"

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.

Skill 2: Work Estimating

I have worked on projects where the program manager, the customer, and I agreed on certain deliverables at the beginning of the project; but over the course of the project, it became apparent that other documentation would be helpful, such as quick reference guides to fill a certain need.

One of the management skills that helps here is estimation. I have made it a practice (and I understand this is generally a good practice) to overestimate a bit on the number of hours I think I will need to complete the documentation for a software application. Then, if I encounter unforeseen complications, I have some extra time to deal with them. But if I complete most of my tasks with some room to spare, I have room later to meet some of those additional needs.

Skill 3: Translating User Stories to Documentation Topics

I’ve written about this one before in some suggestions for Agile technical communicators, but it’s a good one for this subject.

By the time I am asked to give an estimate, the Agile development project has a set of user stories that describe the general functionality that needs to be provided in the application. Many of them translate easily into task-based topics. For example, a user story entitled “Authorize users in the application” will probably mean users will need to know how to get access, to authorize other users, change permissions, or remove users.

Even though user stories (or use cases) start out very general, you can use them to plan out how you will structure the documentation and the approximate number of topics needed.

Skill 4: Matching the Deliverables with Needs

Taking things a step farther from planning doc topics from user stories, ask questions to know who the users are, how many user roles are involved, what their environment is like, and so on. You may have favorite deliverables, but knowing the audience (one of those tech comm statements to live by) will help you select deliverables from the start and be able to expect them throughout the project lifecycle rather than having to introduce something new and hoping you have the room in your schedule and budget for it.
Will you create online help, quick reference guides, release notes, video tutorials, all of it? Getting the facts about the audience first will help you plan your deliverables and minimize surprises.

Skill 5: Flexibility

Planning is largely about anticipation: trying to see what is going to happen and acting accordingly in order to meet it. But one of the synonyms of Agile is flexibility (or change, however you want to look at it). This is the main reason I feel sometimes that I’m being reactive more than proactive. I don’t mind responding to new requests; I would just feel more comfortable and organized if I had planned on them.

Since Agile allows for a flexible schedule and frequent contact with customers, scope creep is a danger. It takes some discipline to avoid scope creep by trading and swapping user stories in the schedule. If something is added, something else has to be taken away in order to keep the schedule and the scope intact.

The same principle applies in Agile documentation projects. If the customer or project team requests some new or expanded deliverable, some negotiation is probably in order. It’s nice to have a bit of padding in your estimates, but if things are running tight, understand and be ready to explain the risks of meeting the request.

As user stories are rearranged in the schedule, be prepared to move documentation tasks along with them. Have contingency plans in the event you become blocked on a task. And of course, don’t be surprised when you learn something has changed.

Wrap-up

After several years working on Agile projects, I’m still working on my Agile documentation project management skills, still trying to get it down to a science. If you have additional skills you rely on for Agile documentation project management, please share them.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. Suggestions for Survival in an Agile Environment as a Technical Communicator
2. Reviewing Projects and Deliverables as a User Education Team
3. Working on Multiple Projects: Positives and Negatives
4. A Bug-Fix Cycle at Project End Is Good for Everyone
5. The Technical Communicator as Project Manager