I’ve been reading Ginny Redish’s book, Letting Go of the Words: Writing Web Content That Works. It was a bit slow at first because the early material is pretty basic. And I came into it with the preconception that it wouldn’t apply much to documentation, since we write help systems and manuals.

In light of our team’s search for the tool that best meets a set of specific requirements, I’ve decided that Redish’s book has everything to do with what I do—or what I should be doing.

My Beef with Tri-pane Help

If you’ve been reading this blog for a while, it’s no secret to you that I’m not a big fan of tri-pane help. I think it’s dated and is associated in people’s minds with unhelpfulness.

But in our search for a tool that will give us a more robust Web output, I’ve discovered the main reason I don’t like tri-pane help.

› Continue reading…

Bookmark It

Hide Sites

I’ve discovered that I write more conversationally when I’m putting together a script for live training or a tutorial than when I’m writing help or other documentation.

Lately, when I’m writing for training, I’m thinking of actually having a conversation, of talking to a real person. When I write other documents, for some reason I’m not thinking this way. It’s a problem because my user assistance content probably comes out dry as a desert in summer. In addition to not being as conscious of users as I should, perhaps there are a couple of organizational factors affecting my mindset.

› 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

Whenever the word documentation escapes someone’s lips, bells go off in my head. I can be sitting (or standing) in a scrum meeting and a developer says, “I’ve been working on such-and-such a task and the accompanying documentation,” and my automatic reaction is to think, “I should be doing the accompanying documentation.”

What he’s talking about is database diagrams (which I’m more than happy to leave to him) or notes from talking to people involved in the business process. I did discover recently that a business analyst put together what he called a quick guide, but it was mostly screenshots and very little text. It didn’t really explain steps. So guess what I’m going to be doing in the near future.

Project teams can accumulate quite a load of documentation over the lifecycle, even aside from any end-user material. In projects I’ve worked on, I’ve seen the following (and probably others):

• Requirements documents
• Concept documents
• User stories and accompanying comments
• Bug tickets and accompanying comments
• Excel spreadsheets with matrices or database code
• Prototype notes
• Wireframe notes
• Visio diagrams of workflows or database relationships
• Samples of legacy reports

I’ve drawn on many of these for my user assistance material. It can be a lot to sift through, and sometimes I settle for asking someone questions rather than wading through the files (gee, that sounds like most of mankind—am I being hypocritical here?). I suppose it’s better that a team have ample documentation than a shortage.

My point is that if your team is going to the trouble of producing this stuff, take advantage of it. On the other hand, lately I’ve felt a little guilty if I wanted to ask, “Is there a document covering this?” as if I’m saying, “I’m antisocial and don’t want to talk to you. I’d rather sit at my computer with headphones on and read my screen, living in my own little tech writing world, than conduct an interview with you.” I’m sure that’s not what the other person would think I’m really saying. In fact, in large part, the developers I work with are as accommodating as they can be and very willing to answer my questions.

There’s a happy medium to be found, I’m sure, as with most aspects in life. If a project has a pile of team documentation, it can be a rich mine full of resources for understanding the product. However, the point may come where you get little return on the time investment and it’s simpler to ask someone. Provided that getting some face time and the answers you need takes less teeth-pulling than going through that project documentation.

Bookmark It

Hide Sites

Because I work on a family of applications that are being developed to replace a legacy program, sometimes my work of documentation and training directly supports the transition from legacy to new. Part of the development team’s replacing and enhancing the legacy functionality is providing a series of reports on data in the systems.

One of my assignments is to provide some documentation that will tell the users how to use the new report prompts and parameters to obtain certain result sets that they have gotten with the legacy reports. My concern with this request is that it is essentially throw-away documentation. Other material I’ve created that relates to this transition period has been around for months and even years now. But we’re getting close enough to turning off the legacy system that I hesitated to produce documentation with a life of only a few months.

› Continue reading…

Bookmark It

Hide Sites

This week, Cameron Moll gave a design presentation to a small group, including our team. He discussed some principles of good versus great design. One of the concepts he brought forward was problem-centered design. As I understand it, a solution-centered design says, “I’ve got this product, so how do I make it do what I want or solve my problem?” Problem-centered design involves focusing on a problem statement to help identify the objective and see the way to design a solution.

I wondered how to implement problem-centered design myself. Applied to documentation, a problem-centered approach seems given to forms like troubleshooting guides and FAQs. The user has a question or problem, so here’s the answer. Simple as that.

I made myself think about it more, though, because if I dismiss it as meaning just troubleshooting or answering questions, I miss a chance to broaden the way I look at what I do and thereby improve it.

› Continue reading…

Bookmark It

Hide Sites

#1

A stakeholder on one of the applications I work on provides support to users in certain roles. Individuals in these roles receive some paperwork upon assuming their positions, and this paperwork points them to the tutorials for this system. I was on the phone with him recently to discuss a change to the online help, and he said,

“When I point people to the tutorials, I rarely get a call back.”

This seems to prove my point that documentation can save on support costs. I don’t think it means that the users take the stakeholder’s response as meaning, “I don’t want to talk to you—go read the documentation instead” and just wash their hands of the whole thing.

#2

In another project meeting, we were discussing a training session for the users. The program manager asked the customer how long the session should be scheduled to take, and the answer was not more than two hours. The program manager said,

“The mind can absorb no more than the seat can endure.”

A good rule to remember when developing training. I found this saying attributed to Janet Trasli on the Web.

Bookmark It

Hide Sites

This post is part of a series on usability and maintainability. At first, meeting the needs of content consumers through usability can seem at odds with meeting needs of technical communicators through maintainability. My purpose in these posts is to discuss how technical communication best practices can satisfy both needs. I’ll use Gurak and Lannon’s usability criteria of users being able to “find what they need, understand the language, follow the instructions, and read the graphics” (A Concise Guide to Technical Communication, 31).

Effective Searching

Text searching has become a prominent, if not the primary, method of locating information electronically, thanks to Google and other search engines. I fall into the search camp; I may glance through a table of contents, but if I don’t quickly locate what I want that way, I turn to searching. Documentation authoring software typically provides a search mechanism for users out of the box, so this provides a bonus for technical communicators through needing little or no maintenance. I mention it here mostly because these days, when people think of finding something electronically, they think search.

Thorough Indexing

Indexing is a leftover from the days when all documentation was delivered in print and that text searching was not available. Some users rely on indexing probably out of habit. But one advantage of indexing is that it acts as a backup in case a search proves ineffective (such as when the same word has a specific meaning as well as a generic meaning in the content—in this case, the search will pick up every instance, while the index will point only to the relevant instances.

› Continue reading…

Bookmark It

Hide Sites