I'd Rather Be Writing » project managers

Findability and The Information Paradox

Tom Johnson — Wed, 12 Jan 2011 14:57:09 +0000

Last year I started a series on organizing content that spanned nearly 30 posts. I want to return to this thread with a summary of why findability becomes an issue for technical writers, and what the information paradox is that we encounter. Then, in an usual ethical twist, I’ll explain why findability might not actually be an issue.

The Documentation Scenario

The help scenario starts out innocently enough. As a technical writer, I document the main tasks users can do in an application. I describe core features and how-to information.

But as times goes by, and I get deeper and deeper into the application, I learn more and more about it — the not-so-intuitive processes, the workarounds, the edge cases, the unresolvable bugs, the usability problems. I transfer this information into the help file because information is my game.

When the app is released, I start to hear feedback from users through various means — calls to the support center, questions during training, emails and conversations. I add much of this information to the help. In the back of my mind, I envision a day when all users can search the help for even the most arcane questions, the most unique situations, and they will find — to their surprise — the answer.

In fact, during one project, I even played a support role for the application. I made it my goal to never answer users’ questions without pointing them to the answer in the help file. This would accomplish two things: (1) it would require me to supplement the help file with possibly missing information; (2) it would increase the user’s confidence in the help. So phone call by phone call, email by email, I added more and more information to the help file until something strange started to happen.

The findability of help topics started breaking down. I reached the point where the help information transitioned from somewhat straightforward to definitely complicated. Each folder had a lot of topics, and some folders had subfolders and subfolders with a lot of topics. I began to forget where some topics were, since they overlapped topically with other folders. I knew that if I forgot where content was, users would have even less of an idea where to look. At this point, I clearly had a problem that I didn’t have when everything was simple.

The Information Paradox

There’s a point at which help files reach a threshold of findability. It doesn’t happen with simple applications — it’s more a problem with semi-large help systems. And it’s also more common when you have a post-release documentation methodology (in which you continue to add the help content after release).

Passing this threshold leads to a paradox that I call the information paradox: The more information you add to a help file, the more informative it becomes because it contains more information. However, as you add more information to your help file, it also becomes less informative because it’s harder for users to find that information.

Here’s an example. Let’s say you just bought a new smart phone. In a weird hypothetical scenario, the store clerk gives you two options for help: you can either have a 5 page quick reference guide, or you can have a 500 page reference manual. But you cannot have both. Which do you choose?

If you choose the quick reference guide, you’ll be able to easily read the information and understand the core tasks, but your advanced questions and tough scenarios might not be addressed. If you take the 500 page manual, it will probably address all your questions, but the process of finding the answers may be too burdensome and tedious to be worth the effort.

The information paradox comes into play here. The more information you add to a help file (in this case, the reference manual), the more informative it becomes because it contains more information. However, the reverse is simultaneously true: the more information you add to a help file, the less informative it becomes, because users can’t find the information. It gets buried among the hundreds of pages.

Here’s an analogy that expresses the same paradox. Let’s say you have a friend who talks your ear off. The more the person talks, the more information is available; with more information, the more potentially informative the conversation is. However, the more a person talks (and yaks on and on and on, talking your ear off), he actually communicates less information, because you start tuning him out. Each new word (or paragraph and topic in a help file) gets diluted in a sea of information until you arrive at the conclusion that he “talked about everything and nothing.”

Document Everything?

Let’s come back to the help situation. My assumption is that there’s a point at which help topics start to break down under a mass of information. When help reaches this threshold, going beyond it actually becomes detrimental to the user because the information starts to lack continuity and focus. It gets sidelined by a myriad of notes, tips, gotchas, quirks, exceptions, side notes, references, extended explanations, details, notices, and other information. A simple process sinks under the albatross of TMI (too much information).

The activity that often pushes help over the edge is the effort to document everything. When I played a support role and tried to answer every user question by pointing users to a link in the help that answered their questions (even if I had to write it before responding), I had an idea of documenting everything. I envisioned a day when I would have a sort of omniscient manual.

But documenting everything is a controversial strategy in technical communication. Some point it out as a myth. Alistair Christie and Graham Campbell had an extended exchange on this topic in one of their podcasts. Let’s suppose they’re right. If you abandon the desire to document everything, and instead only focus on main questions from users, looking at the trends of questions only, do you still run into the information paradox?

If you stay behind that threshold where help still remains relatively findable, are you better off in the long run, and does the whole problem of findability go away? This is a key assumption that begins my discussion on organizing content, because if you don’t document everything, if you only document selectively, chances are your users won’t bang their heads in frustration looking for buried answers. You won’t need to implement advanced techniques for organizing content, and your topic-based folders may not pose any issues with findability.

Expansion and Influence

This isn’t merely a theoretical speculation. I am seriously considering that my strategy for comprehensive documentation is flawed. A couple of years ago, I used to carpool to work with a quality engineer named Kevin. During this time, I operated under the idea that my online help would be a comprehensive source of information for the application I was documenting. It would be the omniscient manual that I was striving for, answering every user’s question. But in our organization, technical writers are scarce resources. Four technical writers try to serve the needs of an 800-person IT department.

In my conversations with Kevin, many times I expressed frustrations with the lack of user assistance on projects in our organization. On many projects, project managers either omitted help or wrote it themselves. Kevin pointed out that if I really felt this way, I should begin a crusade of quick reference guides for as many applications as I could lay my hands on. The information I produce would be short, just a couple of pages, but my reach would be widespread. Not only could I provide the missing user assistance needed for so many applications, he said, with this approach I would also provide users with a form of documentation they would actually read. Like many people, Kevin believed long manuals were unread dinosaur relics that no one used or wanted. My time would be better spent keeping documentation short and sweet. Lots of quick reference guides, lots of projects, lots of influence.

I never followed Kevin’s advice because I couldn’t bring myself to work on a project where my deliverable was only a superficial two-pager with brief information. I couldn’t forego addressing what I felt were the true needs in a help file — those difficult questions that surface from power users and edge-case scenarios. After all, this was my own frustration as a software user: the instructions never seemed to have the answers I needed. But looking back, maybe I should have listened to Kevin.

: The 80-20 Rule: 80 percent of the results come from 20 percent of the efforts.

Kevin’s advice follows a rule know as the 80-20 rule, or the Pareto principle. The idea is that “80 percent of the effects come from 20 percent of the causes.” Let’s say that it takes me 20 percent of my time to create a quick reference guide for an application. Despite only expending 1/5 of my time, the quick reference guide’s effect might influence 80 percent of the users.

This sounds improportional at first, but if you think about it, the idea has merit. Imagine a scenario where you hand out both a quick reference guide and a reference manual to 100 people in a crowd. Assume everyone reads something. About 80 of them would read the quick reference guide , and only 20 would read the reference manual. Right?

Are we technical writers so ethically obtuse that we can’t triage a documentation situation? We end up so bent on writing the all-encompassing reference manual, expending a lot of effort (80 percent of our effort) chasing down answers to arcane questions and edge cases that almost no one needs. Our time would be better spent focusing on the core ideas/tasks and then moving on, leaving the straggling few oddball users to make do without (you know, those users who ask for the full printed manual or who ask about running the app remotely on Ubuntu through a proxy.) Sacrifice a few for the good of the whole. This isn’t murder we’re talking about — just the unfortunate circumstances of time and information. Our influence could be enormous, if we followed logic.

The result of not documenting everything invariably leads to less information. With less information, the help file is smaller and topics are more findable. A quick reference guide that is between 2 and 20 pages in length does not have a findability problem, and the whole information paradox becomes somewhat of a moot point.

In a world of 4 technical writers for 800 IT professionals, the 80-20 rule makes sense. But I also admit that it isn’t ideal. In an ideal world, information is complete; all users’ needs are addressed. Ultimately we continue on with the old model believing that some day, when project managers see our omniscient help systems, which reduce customer support, improve the user experience, and help user productivity soar, they’ll recognize our value and hire more technical writers to document their application. That scenario, however, seems like a day on the horizon that never fully dawns. Maybe we should change our perspective.

Blog Sponsors

Doc Plan Pains and Empowerment

Tom Johnson — Fri, 03 Dec 2010 15:43:26 +0000

One part I enjoyed about my Xtranormal videos was writing the script about the insane spreadsheet that the project manager foists on the technical writer in an effort to track, manage, and contain the writer with busy work. That’s how PM templates have always seemed to me, which explains my reaction when Derek, my colleague, told me he was creating a user education template for a new project management methodology — I wasn’t excited about it. I reviewed it cursorily, nodding in agreement because I really didn’t want to spend much effort with the thing. Looks great, nice work.

I know I like to complain about how technical writers are left out of the picture. Not invited to meetings with users, not adequately informed about projects ahead of time, not invited to the prototype design reviews, not given access to the right environments, and so on.

All this is legitimate, but lately the trend has been swinging the opposite way. Project managers are asking me for help content — early. They’re inviting me to too many meetings. They’re extending a welcome hand into their projects, to review prototypes, to be an influential voice.

Problem is, there’s not enough of me or time to do it all. I thought I could extend my efforts through community-empowered volunteers that I could direct, but that didn’t work out so well. I added project after project on my plate. I have a hard time saying no. Oh, you need some help for an upcoming project? When are you releasing it? Not for 3 months? I can work with that. I can get you the help you need.

I had this same conversation with a handful of project managers, agreed to create help for this and that. Deadlines were too far off to be too concerning. I had billing codes and plenty to do. I had done help for these PMs in the past; why could I not repeat the performance now?

If that wasn’t enough, I started looking for ways to exert some influence in information gaps I perceived in our organization. I read user forums, wrote articles to fill gaps, got involved in even more projects. It doesn’t take much to find a new project. Start interviewing someone about a new app they’re working on, and the inevitable question pops up — what’s your help solution for this application? Oh, we really haven’t thought about that yet. I can help …

Not only do I have a bad habit of saying yes to everything, I also prefer to work outside of strictly defined timeframes and schedules. Give me a release date, tell me what you need, and I’ll create it. That’s my style. But this style starts to implode on itself because every time I see one of the project managers, they want to know the status of the help. And the scope seems to increase. I find myself logging bugs, getting involved in prototype designs, sitting in scrums, triaging issues, deciding on key features, helping customers — in short, becoming the key player that I argued heavily for in my series From Overlooked to Center Stage.

The help doesn’t get written because my time is spread so thin. Right now I’m booked out until at least mid-next year. In a recent team meeting where we meet to discuss standards, I found myself without energy for the discussion about “teeth” and early integration into the software development process. Integration? I don’t need earlier integration. PM’s are integrating me — we just need more resources. Can we hire another technical writer? Can I hire an intern? It turns out Derek had brought up the same question with our former manager the previous week.

At this moment, I started to see the value of this user education planning template Derek was creating. Although I like to do work on an informal agreement and handshake, I realized this method would soon bury me into an inescapable sea of work. Unless I could define the exact work required and the time it would take, I would take on too many projects and end up incapable of delivering the quality of work I want to create. Unless I better defined the scope of the work, the expectations, and the deliverables at the start of the project, I wouldn’t be able to complete the mass of work that I was agreeing to do.

Derek’s 23 page user education planning template hits all of the major components of a documentation plan: objectives, audience, risks and dependencies, localization, SME contacts, milestones, content models, approvals, assumptions, budget, scope, content outlines, strategy, tracking, and more. It’s a document that forces you to think before leaping and agreeing to unreasonable timelines. It’s a document that helps get the project manager on the same page as the technical writer in terms of expectations and realities.

I admit, embarrassingly, that I haven’t completed an official looking user education plan of this scope for years. But I am starting to realize this has been a serious mistake. If I plan to keep my sanity and do a good job with help content, I’ll need to more carefully anticipate the work and requirements for the projects I take on. It’s better to do a good job with help content on a few projects than a scattered, half-effort on a large handful of projects. In the end, rather than a brick that drags you down, the doc plan is like a life-saver buoy that keeps you from drowning.

A documentation plan can save you from drowning in a sea of unreasonable project requirements and time frames.

Blog Sponsors

Tactics for Survival: A Technical Writers Field Guide to Overcoming the Forces of Petty PMs and Broken IT Environments

Tom Johnson — Mon, 22 Nov 2010 14:53:58 +0000

Tactics for Survival: A technical writer's field guide to overcoming the forces of petty project managers and broken IT environments

Last week I attended an STC chapter event that consisted of educators and practitioners discussing educational programs and workplace realities.

Most of the discussion focused on tools, which is a constant topic in these discussions. What tools should educators teach? How do they gain access to tools? Can you learn a tool enough during the trial period? Can you substitute open source tools for industry standards? Which tools should students focus on?

The discussion on tools is not a trivial one. But tools too frequently dominates these academic-practitioner discussions. Rather than a discussion about tools, I want to learn is how educators are preparing students for workplace realities — not in preparing students to accept workplace realities, but how they’re preparing students to resist workplace realities.

The old paradigm of preparing students to excel in the workplace can be misguided. Sure we want to prepare students for the workplace, but we don’t want to prepare them to accept bad workplace practices. We don’t want educators to fashion students into sheep to trot the path laid out before them. Students should not be conditioned to passively use the outdated tools they’re told to use, to produce the static deliverables they’re told to create, to conform to the last-minute documentation efforts expected by petty project managers.

If educators prepare students to adopt a broken IT workplace, where they will be happy in marginalization, content in absence, and silent in requirements, they do their students and the profession a disservice.

When educators prepare students for the workplace, the preparation should involve two components: (1) an awareness of common workplace practices for tech comm, and (2) an awareness of how workplace practices with tech comm should be. The second awareness is more critical than the first. Students should not only recognize poor tech comm practices in the workplace, but be prepared to rise up and correct them.

I outlined the worst case scenario of workplace practices with my Xtranormal videos. Most people who watched the videos agreed they were “painfully true.” Rather than preparing students to perpetuate these bad practices by suggesting the workplace environment is a reality they must prepare for and accept, education should empower students with tactics for survival and success.

For example, students should be empowered to overcome the following workplace scenarios:

A project manager excludes the technical writer from reviewing the language on prototypes.
A project manager doesn’t involve a technical writer until a week before release.
A subject matter expert ignores requests to review documentation.
A department head assigns more projects to one technical writer than is feasible.
A project manager believes a technical writer’s only role is to make the sentences grammatically correct.
A project manager wants to lock down wiki pages from community editing because he or she fears edits.
An interaction designer fails to include a help button in the prototypes and only adds one at the last minute in the footer.
A manager doesn’t want the technical writer to create screencasts because he or she believes only a professional audiovisual expert should create them.
A committee meets to collaboratively write a script for a software demo — the end result is 10 minutes long, wordy, and chaotic.
The CIO believes in user education but does nothing to encourage or champion the cause; in the end, everything else always has a higher priority.

These are the realities of the workplace. I hope tech comm educators aren’t preparing a whole new crop of sheep to accept and endure these practices. I hope they’re teaching students to be empowered, self-willed, independent thinkers and contributors. I hope they’re raising up little firebrands to transform bad workplace practices.

How exactly do you teach this kind of self-empowerment, to reject workplace status quo and work to change broken policies and procedures? How do you convert a group of introverted writers from a model of yes-sir-ism and yes-ma’am-ism to a freedom fighting tech comm strategists?

If there isn’t a required course on it, there should be. Academics just need the right textbook. I’d call it Tactics for Survival: A Technical Writer’s Field Guide to Overcoming the Forces of Petty Project Managers and Broken IT Environments, or something like that. Given all the discussion about this topic on forums, listservs, and blogs, I’d be surprised not to find some published work already written. I believe students will get more benefit out of a 100 page book with 10 essays on this topic than they would the 400 page all-encompassing reference manual on “Technical Communication” that I flipped through while listening to a discussion on tools.

I have a lot more to say about this topic, so I’m marking this post into a series called “Workplace Practices.” If you know of a text that outlines best practices for tech comm in the workplace, let me know. If you’re interested in writing a guest post on this topic, also contact me.

I realize it’s a little aggressive to expect entry-level technical writers to be capable of transforming a broken IT environment, but too often practices at the beginning of one’s employment transition into the way things are done in the future.

Blog Sponsors

10 Quick Tips for Project Managers about Help Content

Tom Johnson — Thu, 11 Nov 2010 15:24:38 +0000

10 tips for PMs about help content

As a follow-up to my last post, When Help Content Is Forgotten, my colleague pointed out that having a set of agreed-upon best practices for technical writers is one of the first steps in establishing traction with project managers. Otherwise, project managers can resist or dismiss a technical writer’s recommendations as subjective opinion.

In an effort to be concise, here’s my stab at the ten things project managers should know when working with technical writers. Imagine formatting these ten sentences in a neat little card that you periodically email to project managers, or that you give project managers when meeting them for the first time. I made them concise so that they’ll be read. These are the 10 concepts that all project managers should know about help content.

10 Best Practices for Help Content

Allocate budget for help content in your project plan.
After your project is approved, contact a technical writer about deadlines for deliverables.
Recognize that what seems intuitive to you may be unintuitive to users.
Technical writers need access to test environments, prototypes, and dummy data.
The user interface is driven by text, so involve a technical writer’s language expertise with prototypes.
Because help content is part of the user experience, technical writers work closely with interaction designers.
Expect short guides and visual content rather than long manuals.
If collaboration and distributed ownership are important, consider a wiki platform.
Technical writers are your application’s first users — their feedback can improve usability.
Documentation isn’t finished with the application’s release, but continues as users submit feedback.

Blog Sponsors

When Help Content Is Forgotten

Tom Johnson — Wed, 10 Nov 2010 15:51:11 +0000

What's missing from this project plan? Its absence is glaring and painful for technical writers

In recent posts on content strategy, I’ve written about how common it is for “user experience” designers to create websites without considering content. I made this point in my last post, Text Matters, and it’s what fuels the fervor behind content strategy.

In the same way that user experience designers forget about web content, replacing empty spaces in their prototypes with lorem ipsum filler, project managers do an even better job of forgetting about help content.

Content strategy may seem new (and all the discussions about web content being forgotten in website redesign projects), but help content has been marginalized in tech comm since time immemorial. Today our user education team was sitting around in our weekly team meeting, talking about ways to ensure that help isn’t forgotten in project plans.

To illustrate, just last week a project manager emailed me about help solutions for a site launching in a week. Other times project managers come to us at the ninth inning of their projects, when all money is gone and the only remaining budget allows for just a few days of labor. Other project managers suddenly inform us of help needs when the only timeframe to complete the work will require full-time commitment on their project from the first contact until release.

Two Types of Content

In the two situations I’ve mentioned — the project manager who forgets web content and the project manager who forgets help content — “content” doesn’t mean the same thing. On a website, content is the main text, audio, video, and images that users will look at, read, interpret, think about, apply, comment on, and so forth. Content drives the heart of a website.

With an application, however, help content isn’t the focus. Applications do many different things, but frequently applications are a platform for users to create content, such as documents, presentations, projects, agendas, lists, and so on. Think of PowerPoint, Basecamp, SharePoint, or even Twitter. What’s the content in those applications? There is no content, for the most part. The user creates the content. The application offers functionality.

When we talk about help content, clearly help content shouldn’t be on center stage like website content. Help content is an emergency kit in the back of your car, available when you need it. Because of this nature of help content, it’s understandable that project managers would forget it. I don’t even have an emergency kit in my car, for example.

Different Content, Same Question

Despite the different types of content, the problem is similar: project managers forget about content. Website project managers forget about the creation of web copy. Application project managers forget about the creation of help content. (Either they forget or they willfully neglect / postpone it.)

How do you help project managers remember web/help content for their site/application? One of my colleagues is so driven to solve the problem that he emailed the CIO and arranged a meeting with one of the top three decision makers in our organization. It was a positive meeting with many heads nodding in agreement.

But a week later, we sit around asking ourselves if anything will change. Will things be better? What will it take to firmly cement user education into the software development process in a way that has “teeth,” as we kept phrasing it? We need teeth to ensure we’re not forgotten. It’s not enough to acknowledge the problem and agree that user education shouldn’t be called at the last minute. We need teeth, dang it. And we want to lock those teeth down on something and hold it like a pit bull clamps down hard on anything between its jaws.

We need teeth like a pit bull. (Photo by This Year's Love on Flickr.)

I’m curious to know if any of my readers have found a workable solution for large organizations such as ours, where new projects come out of nowhere with little or no warning, where the right hand and left hand are autonomous agents acting independently. If you work in a small company where you eat lunch together daily, you may not face this issue. Even mid-size companies with a highly standardized documentation process might not have this problem. We’re more like a full-size startup organization when it comes to tech comm. Our ratio of tech writers to other IT personnel is 1:200.

Brainstorming Ideas

Since this blog is often a brainstorm of ideas enriched by reader comments, I’ll offer a few ideas for helping project managers remember the help content. You can add your own ideas in the comments.

Idea #1. Insert TC into the approval process. Insert a clause in the software development process that requires sign-off from a technical writer before a project gains approval. Almost every IT shop has a project approval process, right? A system of checks and boxes before the finance guys write the check? The problem is in understanding this mysterious process, leveraging the power to change it, educating project managers about the change, and enforcing it. It’s kind of like moving the Titanic onto a new course with a spare oar.

Idea #2. Designate a new project scout. Designate someone to be a scout in the project approval process; make it the person’s job to continually scan for new projects coming down the way. This person may search a project database daily, making contact with project managers to find out information. Or he or she may have close ties with the lead over project managers. (Someone has to allocate a project to a project manager, right?) Maybe the scout sets up regular meetings with this individual to learn about new projects. The only problem is that this meta project manager no doubt is high profile and busy, with little need or care to meet weekly about documentation that his or her project managers should have to deal with.

Idea #3. Bill support costs into projects. Hold project managers accountable for help costs. In a dream world, project managers would have to factor in costs for all support, which means they’ll do everything in their power to minimize these costs up front by providing proper documentation and training. The only problem is that allocating support costs is nebulous. Does the project pay for the health benefits of each support agent, as well as their office space? And how can you budget for something that may be ongoing for years? I wish ITIL recommended a model that considered this idea.

Idea #4. Educate project managers. Start an organization-wide campaign to educate project managers about the need for help, when they should involve technical writers, how many hours to estimate for a project, and such. Hold a regular training for project managers that is ongoing, such as monthly, and invite them all to attend. Begin a campaign of continual education. Even if the project managers keep hitting Decline on meeting invites, they’ll get the point sooner or later. This idea, however, assumes project managers forget help not out of willful neglect, but out of dumb ignorance. This may not be the case at all.

Idea #5. Convert UX to champion CS. Almost every application has an interaction designer or user experience person on the team. Although some UX types don’t want to focus on content, working with and converting the UX lead about the importance of content can give you the leverage of an insider championing your cause. The only problem is that with application development, many UX designers feel a well-designed application won’t need help. Since they plan to create a good design, why would they start thinking about help so early? Doesn’t that admit defeat before the design challenge even starts?

Conclusion

I doubt that any process to help project managers remember content will be effort free. Most of these efforts will require time — maybe 25 percent of someone’s time. Usually technical writers are already so busy working on multiple projects, especially last minute projects, they rarely have time to devote to organizational education campaigns or extensive searches of new projects.

Even if you do have extra time, it’s not often that tech writers have the tenacity to schedule meetings with people three levels above their pay grade to nag them about “documentation.” I know I would feel uncomfortable sending regular emails to the CIO. Maybe this is the real battle: overcoming a feeling of insignificance. Our silence only furthers the degree to which we are forgotten.

Blog Sponsors

Do Some Project Managers Suffer from the Dunning-Kruger Effect?

Tom Johnson — Wed, 07 Jul 2010 14:34:28 +0000

Errol Morris has a lengthy essay in The New York Times on something known as the Dunning-Kruger Effect. Essentially the effect is that even though something is obviously wrong, a person is incapable of recognizing it. Cornell profesor David Dunning stumbled onto the idea when he read about a bank robber who squirted lemon juice on his face, believing that the juice would mask his face from the security cameras.

Dunner writes,

If Wheeler [the bank robber] was too stupid to be a bank robber, perhaps he was also too stupid to know that he was too stupid to be a bank robber — that is, his stupidity protected him from an awareness of his own stupidity.

He later phrased the assertion more academically:

When people are incompetent in the strategies they adopt to achieve success and satisfaction, they suffer a dual burden: Not only do they reach erroneous conclusions and make unfortunate choices, but their incompetence robs them of the ability to realize it. Instead, like Mr. Wheeler, they are left with the erroneous impression they are doing just fine.

To read the full essay, see The Anosognosic’s Dilemma: Something’s Wrong but You’ll Never Know What It Is (Part 1) – Opinionator Blog – NYTimes.com. (Thanks to Bokardo for the tip.)

The Dunning-Kruger Effect might fit nicely into the IT software life cycle. Could we say that project managers who don’t involve technical writers into their workflow to provide help for their product may fail to do so in part because of the Dunning-Kruger Effect?

It’s obvious that most software applications need help material, and you can frankly tell some project managers that their product needs help, that it’s unintuitive, that the help content the project manager may have written is insufficient, but sometimes you may as well be talking to a grasshopper, because the project manager continues forward with the same help-less plan he or she had from the beginning.

It’s not that these types of project managers are incapable or incompetent. So maybe it’s not a real case of the Dunning-Kruger Effect. In a true Dunning-Kruger Effect, there might be something wrong with project managers’ brains that prevents them from ever actually understanding or grasping an actual need for help material. Instead, it’s more a matter of project manager’s inability to recognize a situation due to certain blinders that hide reality.

Project managers often can’t recognize that their decision to exclude help material is wrong because of three underlying reasons:

Having helped build the application from scratch, project managers are blind to their own product’s complexity.
Because they are rarely immersed in actual user environments, project managers are unaware of the user’s knowledge level.
Because they can read and write, project managers assume they can create help materials as well.

Whereas I used to believe that project managers excluded technical writers out of some skilled knowledge about the uselessness of help and their own distinguishing intelligence about user needs, the Dunning-Kruger Effect helped me see that project managers probably have no recognition of any wrongdoing. Their own ignorance in this area protects them from the guilt of what would otherwise be a crime against the user.

Unlike the Dunning-Kruger Effect, the situation with project managers is correctable. You can — through careful, tedious, and tactful perseverance — persuade a project manager to see a new perspective. The approach to bring a project manager into the light of higher understanding involves three strategies:

1. Reveal the Product’s Complexity

If you create a software application from scratch, putting together the requirements, outlining the design specifications, reviewing the prototypes, attending countless project meetings discussing the product — then surely you’re at a disadvantage when it comes to seeing the product from a fresh, uninitiated perspective, as a typical user would. The knowledge a project manager has about the product gives him or her an overbalance of assumptions and background information that make it difficult to see the reality of a product’s complexity.

As the product nears release, project managers often start user testing, that is, they give beta versions of the product to users to explore and test. It’s about this time that project managers begin to realize that their product is more complex than they previously assumed. They start to see the need for help materials for users. For this reason, it’s important for project managers to be involved in user testing — so they can observe first hand the responses of those who lack the same background knowledge that the project manager has.

2. Expose the User’s Knowledge Level

The second blindness that afflicts project managers is unawareness of the user’s knowledge level. This blindness is usually cured through user testing as well. In general, it’s common for project managers to judge an application’s complexity by asking where they themselves would need help. Never mind that the project manager is usually a tech savvy IT professional, and our users barely get by in Microsoft Word. The project manager’s outlook about the user’s ability starts with questions like, What do I find confusing here? What isn’t immediately intuitive? Where are my pain points in the application?

These are good questions — don’t get me wrong. The problem with these questions is that users often start from an entirely different skill level. Most likely users don’t sit in front of computers all day building and managing software. In fact, users may only use the computer for one to two hours a day! Because of this extreme difference in skill level, the project manager becomes blind to the idea that users may not understand when to single or double click, or how to perform simple computer tasks like changing their computer’s resolution or recognizing when a browser window minimizes instead of closes. The user’s questions may be much more basic, such as Why would I want to use this application? Or, How does this fit into my own business workflow? Or, Why can’t I export everything into Microsoft Word?

3. Show the Project Manager’s Writing Weaknesses

The final blindness that makes project managers mistakenly omit technical writers from the software workflow is the perception of their own help authoring ability. Many project managers usually aren’t skilled enough writers to judge their own writing level, so they look at what they’ve typed and see nothing wrong with it. The text and screenshots they’ve pasted into Microsoft Word and the way they have passively constructed their sentences look entirely fine to them.

Helping project manager’s recognize that something is wrong with what the help material they’ve created requires some tact. If you confront the project manager with accusations about poor grammar, lack of organization, and flatness of design, the immediate reaction will be that your motive stems from resentment. You have no credibility when you seem to be operating out of jealousy and exclusion.

Instead, the technical writer must confront the project manager indirectly, perhaps through an objective third party who has a greater awareness. Or through user testing, or through some other objective analysis.

Conclusion

Whether this whole Dunning-Kruger Effect fits the scenario of project managers, I’m not sure. But it has given me a doorway into a topic I’ve been reflecting on for some time — why some project managers don’t/can’t see the value of involving technical writers to create help material. The project managers who exclude technical writers from their projects may do so only because, like the bank robber, they’re too uninformed to realize that they are uniformed about the need for help content.

As we reveal the product’s complexity, expose the user’s knowledge level, and show the project manager’s writing weaknesses, we can help bring project managers to a greater awareness so they can make more better decisions.

Many times the realizations for the project manager come naturally through user testing. I find that I’m often brought onto projects at this time. But by the time the users are testing the beta version of the product (usually one month prior to release), the window of time is usually too brief to produce quality help materials. Consequently, many of the project manager’s erroneous assumptions are actually confirmed.

Blog Sponsors

Why Software Applications Need Product Blogs, and Why They Don’t Get Them

Tom Johnson — Thu, 17 Apr 2008 04:00:32 +0000

Even though I’m an advocate of blogging and think it’s critical to tech comm, I’ve always been assigned technical documentation projects for internally used, confidential, or classified software. Documenting products promoted on the web has never been an option for me.

However, I’m convinced that even internal software, which never sees the light of WWW, still needs a blog as much or more than products sold online. Even so, numerous corporate restrictions, standards, and culture will present seemingly insurmountable barriers to blogs.

I can think of six major ways product blogs can benefit users and project teams. Product blogs can

Provide a venue for product announcements
Allow users to submit product bugs
Allow users to submit feature requests
Provide a roadmap preview for the product
Enable a point of connection between users and project teams
Provide a way to teach advanced tips to users

The following sections expand on each point above.

Provide a venue for product announcements

If you have a new release, you want users to know what new features and fixes are available. With software that runs from a browser, users may not know an upgrade has taken place. Additionally, if you’re offering training or new services, such as a training environment they can explore, you need to let users know.

A blog can be a perfect way to let people know what’s new. For example, today I learned from the Visual Lounge blog what’s new in Camtasia 5.1. I loved finding this announcement in my feedreader (rather than getting an email blast).

Allow users to submit product bugs

Sure your Quality Assurance (QA) team tries to find all the bugs in the software, but if you allow users to submit bugs, you multiple your QA team of 1-3 people by 100 or more. The QA team usually has set scripts they run over and over to test the software, but they can’t know the hundreds of ways users are using and abusing the software. Your users can submit an enormous amount of bugs if you just let them.

For example, Madcap Software has an online bug submission form. I’ve submitted more than a dozen bugs through this online form. Through your blog, you can easily add a tab or button that enables users to submit bugs. Of course you don’t need a blog to collect bugs, but at least with WordPress, a built-in contact form is easily available (see the Dagon Design Form Mailer plugin). Making bugs public allows other users to be aware of potential pitfalls. And you can provide workarounds or fixes that all users can benefit from.

Allow users to submit feature requests

How do you gather feature requests from a wide user base? Like most people, I often have suggestions to improve the usability and features of the software I use. Because of the interactive nature of blogs, it’s a natural fit to provide a feature request form on your blog.

If the feature requests are public (such as a comment thread on a post), other users can comment on the requested features. In fact, you could incorporate a rating form that would allow users to quickly indicate how much they wanted such a feature. You could then make better informed decisions about the priority of enhancements. This method avoids the problem of polling software requirements from a narrow user base.

Provide a roadmap preview for the product

Especially with agile applications, users want to know what enhancements are coming. On your product blog, you can provide a roadmap of features in development. This would allow users not only to be less frustrated with current system limitations, but would also clue them into the fact that upgrades are coming. I find that many users have no idea when upcoming releases are scheduled nor when they’re released. They don’t know if they’re in 2.1, 2.2, or 2.3. They’re just “in the application.”

But with a roadmap preview, users can see what’s coming, when it’s coming, and what the new release will include. They’ll be more patient, knowing that developers are actively working on problems and enhancements, and they’ll feel part of the excitement of a live, actively developed application.

One of the things people like most about WordPress is that its in active development. Releases come out four times a year. With every release, users get really excited. In fact, the release of 2.5 was announced as the kickoff for Matt Mullenweg’s keynote at Wordcamp Dallas.

Enable a point of connection between users and project teams

Perhaps the most important benefit of the product blog is to enable a point of connection between users and project teams. Blogs provide a way for users to contact actual project members, to express their concerns or requests, and to otherwise interact.

Likewise, blogs allow project members to connect with users. Allowing people to connect and communicate is huge. It’s the phrase Mark Zuckerberg kept repeating at his keynote at SXSW, attributing Facebook’s success to the way it allows people to “connect and communicate” with their friends.

With large companies such as Microsoft, Adobe, or Apple, I don’t feel like I have a connecting voice. I have no idea who to contact, and even if I did have a contact email, the person (usually in Marketing) is so removed from actual development that I doubt my communication ever has an impact. In contrast, blogs make everything transparent and interconnected.

Provide a way to teach advanced tips to users

Users often don’t realize that even though they’ve learned the application, they may be using it inefficiently. Once the user gets past the novice stage, they rarely consult the help. They get trapped in inefficient practices without realizing it. Through the blog, you can deliver more advanced tips that users may never be aware of, even if the tips already exist in the help.

Additionally, because blogs give the instruction in short bursts, users won’t be overwhelmed (such as with a 200 page user manual). They can quickly skim a blog post and get the gist of the instruction. You can hit them with some advanced tips every week, spoonfeeding them into power user status.

Corporate Challenges to Product Blogs

On the web, you can easily install a robust blog platform, such as WordPress, and modify it with all the features you need. In fact, if you get a hosting plan with a company like Bluehost, setting up your blog is a 2 minute process (see their Simple Scripts feature). However, installing a blog on corporate server space behind a firewall is beastly, for the reasons listed below.

Approved Technologies Only. Most interactive software runs on PHP, requires databases such as MySQL, and has other server requirements. Companies often have strict infrastructure guidelines that aren’t very tolerant of open source software. If your company has chosen not to use PHP, or uses only Oracle or SQL Server, or restricts everything to Java, you’re in for a battle. (By the way, an alternative blog platform that runs on Java is Roller. Looks complicated to set up, though.)

No Server Space for Help or Blogs. Even more problematic, many times your infrastructure team won’t give you server space at all, much less space to install a blog. SharePoint possibilities may exist, but SharePoint blogs are usually primitive (for example, there’s no “read more” tag), and SharePoint can require users to log in before they can read your blog.

False cultural beliefs about blogs. Cultural shifts are also a big hurdle. A blog in the mind of your CEO or CIO may conjure up images of MySpace and Facebook, or opinionated ranters, or videos of cats playing the piano. You’ll have to sell the idea of a blog. Maybe ditch the word blog and call it a new media site where users can interact. I don’t have much advice here other than to be persistent. The squeaky wheel often gets the grease. If you mention how your competition is using the software you need, it will boost your case.

Employees don’t use RSS readers. Finally, employees at companies rarely use RSS feeds, so delivering your blog will be difficult. Sure they can download a feedreader, but if yours is the only feed to subscribe to, fat chance. Perhaps you can convince developers to add a link that says “blog” next to the help, but you’ll really have to convert the project manager to Web 2.0. I’ve daydreamed about how to integrate an RSS feed into my online help, but the idea of people accessing help to click a link to a blog is unlikely.

Conclusion

While software products need blogs, getting server space for a blog, getting approval for the blog, finding a blog platform that runs on your company’s approved technology, and integrating your blog into a space where users frequently visit all pose major challenges for blogs in the corporate scene. Still, if you can manage to break through these barriers, product blogs can provide tremendous benefits to both users and project members.