The office staff tended to want to ask me how to do things and be walked through it, but I took those times to ask them to test out the instructions for me. However, on one occasion, I had to guide a brand-new user through a somewhat complicated scheduling procedure while she was on the phone with the person setting up the appointment. I figured it would be better to help her through that one because she’d feel enough pressure from trying to do it right and in a timely manner.

In addition to notes on improvements to make to the guides, I kept other notes. The rundown:

• 5 tasks to add to the guides
• 14 other changes needed to the guides
• 20 feature or change requests
• 10 bugs
• 14 miscellaneous items that were questions, observations, or usability problems

Changes I found I needed to make to the guides:

• Add sidebar for table of contents
• Add several tasks, some applicable across guides
• Change how I give an orientation to system navigation
• Add tips on effective searching
• Change heading styles to stand out more
• Make guide for each role visually different somehow
• Reference material for how different scheduling works for different types of activities

One problem I saw is that users would lose their places when going from a guide to the screen and back because they need both hands to type, so they couldn’t keep their place with a finger on the page. They’d go back to the guide and resume at a random step.

I asked my colleague Tom if he has any techniques for mitigating this problem. We talked about having a two-column layout for the guides with the text on one side and images on the other that have annotations or callouts that tie back to the instructions.

That sounded like a good idea and implementation of the quick reference concept. I had gone pretty minimalistic with the guides, having some orientation material on general application usage, and then the tasks with few images.

Today I tried restructuring one of the guides, and it turned out basically like the image here—instructions, a sidebar with ancillary information, and a screenshot. I have few actual callouts so far. At this point, I’ve mostly indicated only what part of the page each step applies to.

One benefit of this approach is that the steps are quick, and the image also illustrates the steps in a brief way. So a new person could use both, but a more experienced person could choose one or the other. The tricky part will be making it all lay out well and accommodate translations. It will be interesting to test out this approach if I get the chance.

A great result from having participated in the pilot is that the project manager invited me to a brainstorming meeting next week that I believe has to do with design decisions. The product manager called me earlier this week to talk about my visit to the pilot site, and he asked me to prepare any design suggestions regarding the usability problems I saw. It makes the project more interesting for me to participate and contribute beyond just writing end user instructions.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. Project Pinnacle, Episode 2: Drafting Quick Reference Guides
2. Project Pinnacle, Episode 1: Conversation with the Project Manager
3. Try a Quick Reference Guide for Short-Term Documentation Needs
4. Quick Reference Guide Q&A
5. Spending Time with Users to Learn How They Want Assistance

We’ve come to realize that if we want our department to take us seriously and give us the place we want, we need to be equipped to justify the decisions we make on what user education products are right for any given project. One of the things I’d like to see happen in our team is to develop a menu of products, each with a specific definition and an explanation of the situation(s) in which we would recommend that product.

I’ve taken a first shot at this. I’d like your help to flesh this list out, the descriptions, and the reasons you’d use each one. In the comments, please let me know what I’ve left out.

Quick Reference Guide: One-to-eight-page guide that contains reference information, repeatable tasks, or some combination of these. Used when users have small number of tasks or will frequently need to refer to charts, tabular data, and so on.

Quick-Start Guide: One or two sheets that explain the steps for setting something up. Could also provide a set of most common tasks. A throw-away document. Focus may lean toward one-time training.

Short Guide: Thirty-to-forty-page document that provides task steps and reference information. Used when there is too much information for a quick reference guide.

Setup Guide: Document about the same size as a short guide but that is focused on setup tasks. Used when there is too much information for a quick-start guide.

Comprehensive Guide: A full document with fairly complete information about how to complete tasks with the product. Includes reference information and maybe troubleshooting information. Used when a user will perform a wide range of actions with the product, product uses a specific set of terms, and/or product is complex.

Training Guide: A document about the size of a short guide with a focus on teaching the user how to complete core tasks. Concepts build on each other. Examples and exercises are included. Used when someone needs to be trained to use a product by using the product.

Microsoft HTML Help System: A set of HTML files with a table of contents, glossary, and index, all running within a single file (.chm). Installed with software. Used with software installed on the computer hard drive and the user may not have an Internet connection. Contains instructions on completing tasks. May contain context-sensitive topics, reference information, and troubleshooting information.

WebHelp System (or variants): A set of HTML files with a table of contents, glossary, and index. Hosted on a server. Contains instructions on completing tasks. May contain context-sensitive topics, reference information, and troubleshooting information. Used when an Internet connection is common for users.

Knowledgebase: A set of HTML files that contain reference and troubleshooting information.

Web-based Help or Support Site: A dynamic, searchable website containing a variety of topics. Users can comment on topics and browse topics by tag. Allows integration with social media.

Demonstration Video: A recording of the use of a product, usually software, to show how to complete certain tasks. May be used if no test version of the product is available, and practicing with the product isn’t an option. May include voiceover or text captions.

Overview Video: A short introduction to a product that highlights key features. Doesn’t show how to complete specific tasks. Used to give users a brief exposure before they begin using the product or even as an advertisement.

Static Simulation: A video that relies on actions from the user to move forward, typically in what appears to be software. The user must follow a particular path to complete the task, and choices and exploration is limited. May be used as a scripted demonstration so that the demonstration always shows the same functions (and always works).

Tutorial: A blend of demonstration and simulation. Users are shown how to complete a task and then are given the opportunity to try it out.

Wiki: A set of webpages that are editable by any user with an account on the platform. Users can also add and remove pages. Pages have revision histories, and changes may be subject to approval by an administrator. Used when a product has an active community surrounding it whose members are interested in contributing information about the product.

Blog: A website or webpage that is updated regularly, giving updates about a product. Usually somewhat informal in tone. Used when a product’s users want to receive information about a product in between releases.

Release Notes: Short documents, such as a readme file or PDF, that lists the changes in a major release, update, or patch to software.

Inline Help: Text on websites or in applications added to elements to provide some context or examples for using the elements. Used when users may need minimal information to successfully navigate and complete a task.

Embedded Help: Text on websites or in applications that is contained in boxes, sidebars, or modal windows and explains elements in more detail than inline help. Used when further information is required outside the main flow of the webpage or screen.

Tooltip Help: Text on websites or in applications that appears when the user places the mouse pointer over an element for a few seconds. Used when brief hints or reminders are needed and real estate is scarce.

Autocomplete: A text field that provides a drop-down list of options matching typed characters as the user types. Used when only certain options are available, but there are too many to include in a drop-down box, or to provide recommendations.

What would you add? What information have I forgotten from the items here? I’ll update this list based on your comments.

Update: Added release notes, tooltip help, and autocomplete. I wouldn’t have thought of autocomplete features as user assistance, but after it was suggested and I thought about it, I agree. Autocomplete can give guidance so the user doesn’t enter data that the software can’t handle.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. Findings from an Online Help Usability Test
2. Offering a Menu of Tech Comm Deliverables
3. Why a Transition from Tech Comm to Usability Makes Sense
4. A Way to Get Technical Writing Practice
5. Get Passionate about Tech Comm

So, You Need a Book about Usability

A while back, I asked Karen Bachmann, a usability expert in our STC chapter, to recommend some books for our tech comm department. I was looking for a place to start with the topic. Without hesitation, she told me everyone should read Steve Krug’s Don’t Make Me Think.

So, I ordered both Krug’s books: Don’t Make Me Think and Rocket Surgery Made Easy. Rocket Surgery is an expansion on his explanation of how to do simple, cheap usability testing. It comes with great check lists and sample scripts that you can download, along with a free chapter of the book and recommendations on equipment.

Once I had read Don’t Make Me Think, I wanted to send recommendations to our developers. That seemed like an overwhelming undertaking, so instead, after reading Rocket Surgery, I decided to implement a testing schedule for our documentation, with the long-term goal of getting to test our products.

The books are light-hearted reads that make usability seem like common sense that everyone will value if you can just get them to a testing session. And I wanted a project like that. One with value that would be immediately apparent to anyone who dropped by to observe the testing. One that wouldn’t rely on my qualities to succeed, but that could sell itself.

The book was filled with step-by-step instructions for the various phases of testing: recruiting participants, writing the testing scenarios, leading the discussion afterward. Simple. The way I explained it to my manager sounded so simple, too. She approved the project.

Rocket Surgery by Proxy

Ultimately, the testing sessions we implemented differed in some fundamental ways from the process that Krug outlines. This was partly because we were testing proxy users—co-workers who have the domain expertise of our customers. The other variable is that, rather than websites, we were testing complex, highly-customizable products. This issue of testing on co-workers was the biggest challenge to adapting Krug’s method.

Our company builds software to be used by mainly by medical personnel in clinical settings. Many of our product specialists and technical support specialists come from that background.

This was important because we would not be recruiting for participants among our external users. We’d only recently started directly contacting clients. Trying out a new testing process on them was too far outside our comfort zone.

I took an excellent short story class in college towards my Creative Writing degree, and most of the class periods involved intense workshopping of our stories. The problem was, the second time we looked at a story, it was sometimes difficult for us to appreciate the revisions because we compared it to the previous version.

We couldn’t un-know the plot twists, and so we had an insider’s view, even if the twists were better executed in the second draft. The professor called it “pregnant with knowledge.”

Our proxy users, our testing participants, had insider knowledge of the products and sometimes even the documentation. They knew workarounds to find information that real customers may or may not know.

Many times, a participant would make an observation about a frustrating experience, “I wish I could sort here,” but then follow it with either the reason why the improvement hadn’t been implemented yet, “but we did this because we already had it that way in Product X,” or a detailed recommendation on how to fix it, “I was talking with Sue about how we should sort on this page and then filter by release date on the following page.”

My attempts to improvise and make the most of these insights led me off the scripts that Krug provides. I customized the script to fit our situation, as it was. I don’t think these variations produced bad results. It just complicated things. To compensate, I would recommend allotting ample time for creating the testing scenarios.

Kristi Leach is technical writer, content strategist, and recent transplant to the Chicago area. You can read the second part of this post on her blog, Release Notes.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. Six Things to Remember in Your Documentation Usability Testing
2. Some Observations from Documentation Usability Testing
3. Documentation Needs Usability Testing, Too
4. Why a Transition from Tech Comm to Usability Makes Sense
5. Where Usability and Documentation Meet

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.

I called the product manager and suggested that we visit the class with the purpose of seeing if we at headquarters were providing everything needed for these instructors at the training center. It had occurred to me that this was something we should have done a long time ago, back when the application was rolled out. Instead, I had focused on documentation and training materials while remaining unconscious of the actual in-person training that was going to happen.

So sleeping on it did some good. My view the day after was much different than my initial reaction.

The Opportunity and the Result

The product manager thought this visit was a great idea. He, the SME, and I spent an entire day observing the classes and even provided corrections and additional information. We also found that our training system had some bugs in it that prevented the instructors from covering some important material—and from instilling further confidence in the application in the class members. Instead of letting us know, they skipped or worked around the problems.

It was an interesting parallel: We weren’t getting much feedback from the instructors on our materials and what they needed from us; at the same time, the instructors don’t get much feedback from class members on the quality of the training once they’ve begun their assignments.

I found out that the other “help sheets” covered the basics in programs like Word, Excel, and Outlook rather than our custom application. That gave me a little less to worry about.

As the three of us visitors discussed our findings later, the product manager pointed out that the class members were essentially being overloaded with information. They would forget much of what was taught in class and have to relearn it once they began their assignments. But at least they would remember having been exposed to it before.

At this point, I won’t be developing any standardized materials for the classes. But we decided, along with the instructors’ supervisor, that semi-annual visits would be beneficial so that our efforts will be coordinated. For now, the “help sheets” will probably stay as they are. But I took their existence as a cue to improve the help material on that subject to be more comprehensive.

I learned that when I encounter rogue documentation, instead of feeling threatened or replaceable, I should take it as an opportunity to analyze what I’m doing and where the holes are. It’s an opportunity to do my job better.

Art credit: Drawn and colored by Daniel Minson.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. A Little Thing Called Documentation Sprawl
2. Follow-up: A Skill for the Extroverted Technical Communicator
3. Where Usability and Documentation Meet
4. More Than a Technical Writer
5. Team Documentation Design Reviews

A few weeks ago, I got an email stating I was now being followed on Twitter by @helpburner. I thought this could be another technical writer, and I usually check the tweets of people who follow me anyway. Imagine my interest when Mike Stokes, the owner of this account, had tweets mentioning the beta test of a product called HelpBurner.

The HelpBurner blog entry from May 13th says:

HelpBurner is a new way for web designers and developers to create project documentation, visual how-to’s, tutorials and support material… and we guarantee it will take you at least 50% less time, plus the help created will look beautiful!

And later on:

We think it redefines how help, user guides, tutorials etc are created and more importantly it makes help easy to use and empowering for your users (and did we mention pretty). This can only be a great new step for us all and lead to happier customers and more expert users of our products.

Strong claims of course, and the HelpBurner team is working to meet them. HelpBurner, which appears to be a Silverlight application, is currently in beta, and you can download it by visiting the blog post I linked to above.

I started out a little wary because the initial audience is advertised to be Web developers and designers rather than technical communicators. HelpBurner has promising features, though. Possibly my favorite is the ability to publish in an HTML format that looks like a website instead of tri-pane help. The authoring interface is simple and reminds me a bit of WordPress. My biggest request at this point is to be able to define and apply styles instead of just local formatting, which is currently all the topic editor offers.

If you create user assistance, I encourage you to try HelpBurner out and provide feedback. Mike Stokes, a company representative, is very responsive. I’m not sure when the full release will be, but now’s a great time to try HelpBurner and help make it what you want in a help authoring tool.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. Call for Web 2.0–Friendly Authoring Tools
2. Help Authoring Woes: Index As You Go
3. Five Skills for Managing Documentation Projects in an Agile Environment
4. Styles in Inches and Points Improve RH-to-Word Output

“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…"

This is a fairly small project and is phase one of two. The user base isn’t large. When I started on the project, I figured I would just document the new system. Much of the work I’ve done over the last few years has to do with applications that replace legacy systems, and I think this time I may have just overlooked the legacy documentation because of the project’s relatively small size.

Even if I don’t end up using any of the legacy content, it’s a valuable exercise to see what’s there, what the users have been making use of. It’s even better to see what notes they’ve been writing in the margins so I know what kinds of information they find important.

The designer will send me the electronic copy of the old manual, which will be a good start. Next will be a trip to the users’ desks to see their own additions, perhaps what you could call the original wiki. Phase one of the project is nearly over, but I’ll have phase two in which to make any adjustments based on what I find out. It’s been a good reminder of what I ought to be doing when documenting applications that are replacing legacy apps.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. Determining How Much to Document the Transition from Legacy Systems
2. Printed Documentation: Only One Foot in the Grave
3. Team Documentation Design Reviews
4. Minimizing Confidential Content in Documentation Images
5. Express Lane Documentation: Get in, Get It, and Get Out

I once overheard a Web designer say something to the effect that “if an app is designed well, it doesn’t need help,” meaning a help system.

Say what?

In my experience, some applications support complex business processes. Some people say that this means the business processes themselves need to be simplified. Yes, I have seen where a development project has instigated changes in the business, so there is a meeting in the middle. But chances are minute of a new application bringing about a total overhaul of the business process. So the situation still requires that complex processes need somewhat complex supporting software. This makes my job pretty important.

Recently, a developer completed a feature and said to me, “I wouldn’t want to have to explain it.” Granted, he’s a programmer, not a writer, but that made me stop and think.

Therefore, to that Web designer, I would say, “If an app is designed well, it can be easily explained.”

I think that even a complicated system can be explained easily and simply if it’s well designed.

But here’s something to consider: If a feature is difficult to explain, then should it be redesigned? If you can’t write a quick reference card on it, should it be revisited? It would take some bravery to say yes to these questions because there is cost associated with following through. But if it’s hard for a professional writer to articulate, then it may be hard for users to understand.

It’s a tough question, and one I expect most writers would hesitate to raise. Part of the job satisfaction is coming up with ways to help users understand something, and a complex product heightens the challenge. But I’m sure there’s a point where it’s time to push back and say “This is too complicated and hard to explain.”

Where that point lies is a different matter and, unfortunately, is different for each product.

Bookmark It

Hide Sites

Related posts (auto-generated):

1. Four More Reasons Your Company Needs Technical Communicators
2. Does Your SME Know What a SME Is?
3. Seven Reasons Your Company Needs a Technical Communicator
4. Being a Technical Communicator for the LDS Church
5. Enhancements vs. Just Documenting It