In this post I'm putting together a more formal help strategy.

In a previous post, I started to explain my approach to help authoring. I’m trying to flesh this out into a more developed and detailed — but not too long — statement about how I do help. This information would be useful both to project managers as well as other writers I work with. I would appreciate any feedback.

Help Strategies

Because users have different skill levels and learning styles, help material needs to be multimodal in its approach, providing content not only in written format, but also through videos, illustrations, and the interface. With this approach, learning materials for a software application typically include the following:

Videos. Videos are usually brief screencasts that focus on a specific task. As screencasts, the videos are voice-narrated and focus only on the screen, without actors or scenes. The screencasts are short, such as 1-2 minutes, and are created almost entirely by the technical writer. This keeps production costs down while allowing for updates as the application changes. New users, especially visual learners, will typically view a series of videos to become familiar with an application. Videos aren’t meant to address advanced topics or edge cases, but are targeted at new users who prefer to learn by having someone show them how to do tasks.

Quick reference guides. Quick reference guides are usually two to eight page guides containing brief instructions in a visual way. These guides often contain screenshots with callouts and other explanations. The quick reference guides can also include concept diagrams, workflows, and other illustrations to help users understand the application quickly. Text in quick reference guides is brief and compressed, providing more of an overview than specific how-to detail. The basic idea of a quick reference guide is to give the user just enough information to get started in the application. This type of help material appeals to users who prefer some information in a brief, easy-to-digest way as they first jump into an application. Like videos, quick reference guides are targeted to new users.

How-to guides. How-to guides are lengthier printed guides that expand on the application in a more elaborate — but not comprehensive — way. A how-to guide is meant to be read, not merely referenced, and will focus on many concepts and capabilities within the application. These guides are a subset of the total documentation, with topics selected and integrated in such a way as to produce a readable booklet about the software application. These guides are usually single sourced from the online help and crafted in a way to make them pleasing in a print-reading experience. How-to guides are intended for users who want a more in-depth grounding in an application.

Online help. Online help is a browser-based HTML format for help content. Online help is the most comprehensive collection of topics, intended for reference and searching more than anything else. Online help is meant for users who have specific questions or need to search specific how-to’s (often advanced topics) about the application. Online help isn’t intended for people first learning about an application, because the topics aren’t necessarily grouped in a sequential or linear way. Each topic is modular and can be accessed and interpreted independently of other topics.

Interface text. Interface text includes all the language within the interface, from button names, page titles, and error messages to other instructive and navigational text the user interprets to use application. These interface tips and guides are important for users as they explore the interface and learn by doing. Interface text can also take the form of on-screen help text (often shown in hover tips) or as context-sensitive help, which shows a topic relevant to the current page. Interface text accommodates users who prefer to learn by doing.

Help Content

Access to users. Apart from the format, the content of the help material needs to be relevant and useful. In order to produce relevant content in a language and organization that makes sense to users, technical writers need to understand the user’s environment, vocabulary, and tasks. As such, technical writers need access to users. The access could come through phone calls, observations of users, or other interactions. Based on interactions with users, the technical writer may create personas and scenarios to create better help. Personas and scenarios can expand the perspectives from which a technical writer sees an application.

Multiple perspectives. The paradigm of a single author working from a single perspective, usually as an outsider to the actual business context of the application, is a paradigm that typically fails, since no one person can know all the information needed to help users. Contributions from multiple perspectives — from project stakeholders, project team members, community volunteers, and end-users — will help the content reach relevance and usefulness for a larger number of people. The importance of collaboration requires an approach that facilitates multiple authors and distributed ownership.

Editorial roles. Because of the need for distributed authoring, subject matter experts may often be content contributors. In these cases, the technical writer acts as an editor to help style and review the subject matter expert’s content. Other times, end-users themselves may contribute toward the content. User contributions should not be discouraged, nor should it be difficult for users to contribute or provide feedback. Heavy content collaboration may be facilitated through a wiki platform, but not necessarily. Other methods for interacting and content sharing can also be employed, such as with forums or comments below topics. In each case, the technical writer either edits or facilitates the content rather than creating it from scratch.

Perpetual beta. When the application is released, content is not finished. Even though content may be in a semi-complete state, we can never anticipate all the gaps, needs, quirks, and issues that users will encounter pre-release. For this reason, content needs to be published in a perpetual beta state, that is, with the ability to continually update the content even after release. As such, the help content should be stored separate from the application code to avoid release-window-only time frames. Technical writers should be able to update any help content on the fly as needs arise. Because help is usually stored on another server, applications requiring login should employ single-sign-on to reduce a secondary login windows.

Agile feedback loops. Just as the agile process often results in better software development, the same agile process applied to help material can be beneficial as well. To be agile, technical writers need to actively gather feedback about help material to improve it. Feedback from documentation doesn’t always need to be expressed as comments. Technical writers can gather feedback through metrics and other automated processes. Each help topic should contain tracking code to measure hits. Attending live training (or providing live training) and observing users can also be a means of gathering feedback. Technical writers need to be attuned to bug logging systems so they can connect with project team’s tracking of issues, and with the support center so they can monitor incident logs. Communication with product managers is also key to gathering verbal feedback. Where possible, technical writers should automate reports and other feedback on a regular basis and update the help accordingly.

Scope of information. Despite the attempt to provide business relevant content to every user, documentation does not need to provide instructions about everything. Too much information can make it difficult for users to find what they need. An over-abundance of information can dilute core task content and need-to-know topics. However, the technical writer does attempt to provide instructions for at least 80 percent of the typical user’s needs. Efforts to document the remaining 20 percent often fall prey to the law of diminishing returns; that is, for the effort required (tracking down hard-to-find solutions for unlikely scenarios), the payoff is little.

Help Plans and Processes

Prototype language. Technical writers should be involved in projects as soon as prototypes have been created. This early integration is necessary for technical writers to address interface language while there’s still time to make changes. Interface language is a component within the technical writer’s domain of expertise and should be treated as such. Technical writers should work closely with interaction designers in refining prototype language to avoid ambiguity — particularly in global contexts. Projects in which interaction designers are employed at the beginning, and technical writers at the end, often end up with broken interfaces.

Project plans. Technical writers should complete a project plan that provides project managers with a general estimate of the anticipated work and other details for the project. As an industry standard, it takes approximately four hours per application screen to create a help topic. This estimate of time for help topics only, and does not include time for creating videos, quick reference guides, or interface language. The project plan should also address the deliverables, expectations, risks, scope, timeline, and other details for the documentation. Failure to produce a project plan can result in a misalignment of expectations between project managers and writers.

Dual roles. Many times the technical writer becomes a subject matter expert on the application, having explored and examined it at length. The technical writer may become aware of bugs, usability issues, and support requests for an application. However, given the limited technical writing resources available, technical writers should only play these additional roles briefly. Technical writers may log or report bugs, but not necessarily flesh out the exact steps for reproducing bugs in every browser, nor conduct extensive usability testing, nor play support roles on the phone with end-users. If technical writers do play multiple roles on a project team, as is sometimes necessary in agile environments, project managers need to factor in this additional work into the project plan and estimated hours.

Approval processes. Before help materials can be considered complete, they must undergo review by several parties. The project manager should designate someone from the project team to review the accuracy of the help material. (Many times project managers themselves review this material, or assign quality assurance leads.) Other reviews may also be necessary if distributing the content externally. These reviews will add additional weeks into the completion of the help material. The reviews serve several purposes: to ensure consistency of style, to mitigate legal risks with content, and to provide another perspective on the coherence and accuracy of the content.

Tools and Technologies

Tools. Technical writing teams should use the same general set of tools so they can collaborate on files, share tips and how-to knowledge, and be interchangeable on projects. If one writer’s load becomes too heavy, he or she can re-allocate the load to other writers as long as the others can pick up and use the same tools. In most cases, use industry standards rather than open-source tools. Team members should also have the latest versions of each tool to facilitate collaboration.

Collaboration and content re-use. If external collaboration (such as with the community) is important on a project, a wiki works well. In fact, collaborating with large numbers of people in real-time is probably only feasible through a wiki, but the wiki doesn’t need to be the end product (the material can be exported). If only internal collaboration is important, other strategies may make more sense, such as a help authoring tool that stores content in a content management system. Ideally, if all internal collaborators can access and author from a central content management system, and render the outputs in a standard way without resorting to individual formatting, this can help with consistency and reduce the technical burden on content producers.

Corporate constraints. In a large organization, requiring every employee to standardize on the same toolset is difficult. Additionally, many times corporations limit certain tools and technologies from being installed. One must always work within a given environment while at the same time making strides to obtain approvals for more appropriate tools and technologies. Making appeals to industry standards can provide some leverage. Regardless, one can often accomplish the same results using many different tools and technologies.

Constant learning. Because technical writers often handle all aspects of content production, from creation to design to publishing to distribution in a variety of formats, including text, illustrations, video, and e-learning, the technical writer must constantly be engaged in learning tools and technologies. It’s not strategic to wait until the tool knowledge is required and a pressing deadline looms near. Rather the technical writer should schedule regular learning time, perhaps accessing sites like Lynda.com, into his or her daily schedule. When opportunities arise, the technical writer can leverage this knowledge to quickly design, illustrate, record, compile, call, style, or configure help content as needed. This learning is part of the technical writer’s job, and is an element that separates technical writing from many other types of writing.

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

Second, the interplay between simplicity and complexity is what technical writing is all about.

Although simplicity is a noble ideal, and something like “simplify complexity” could be the mission statement of any technical writer, simplicity is in fact a complex undertaking.

Let me explain with an example. If you look at any TechSmith help file, the author tries to make the content as simple and accessible as possible because TechSmith wants users to feel the inherent ease and simplicity of the application. Topics are light, short, easy to navigate. It’s quick to see what’s there.

This model works fine for the basic user just trying to get up to speed, but it fails the power user. If you look at TechSmith’s forums, users have written Support asking hundreds of questions, many of which aren’t answered in the help. For example, how do you reduce AVI file size? The treatment in the help is light, but the support forum is heavy.

TechSmith Support Forum

This is the supposed tradeoff between simplicity and complexity. If you keep it simple, the documentation is accessible and easy to digest, but it may not answer many of your questions. If you try to answer all of the reader’s possible questions, the help becomes thick and heavy and the product seems complex.

WordPress is another example. If you know what you’re doing, installing WordPress really only takes 5 minutes. However, because there are a dozen different install methods (depending on your web host, the database tools, and your server access), and because various authors have added their how-to’s on the installation page, installing WordPress looks complicated.

Choosing between complexity and simplicity in documentation

Sure the WordPress wiki authors could strip out the installation instructions and target them for the most likely user (applying the 80/20 rule), but then the other 20% whose server setup is different from the install instructions would have trouble.

Many people will look at the tradeoff between simplicity and complexity and leave it at that. If you want it simple, you have to dumb down your documentation and leave out all of the exceptions, notes, what-if-scenarios, and other gotchas. If you want to include all of the info every possible user may ask or need, in a variety of situations, you’ll end up with a complex looking help application that intimidates users. This is the perceived tradeoff between simplicity and complexity, and it’s partly a myth.

This is where the skills of technical writing come in. A good technical writer can add in all the complexity of the system – the notes, tips, cautions, what-if’s, remember-this, watch-out-for-this-gotcha, if-you-have-this-platform, for this and that scenario – and so on, without having the help file degenerate into a hairball of complexity. This is what separates trained technical writers from basic IT people who can write coherently.

Almost every best practice of technical writing is aimed at simplifying complexity. The more techniques you employ in your help, the more powerful you become at compressing information into your help file without cluttering it into confusion.

Here are 20 techniques most experienced technical writers implement almost unconsciously.

1. Approach the application from a task-based mindset rather than a screen-by-screen mindset.
2. Break up the material into discrete topics that you can manipulate into different outputs.
3. Use numbered steps in your tasks.
4. Keep the number of steps relatively short — no more than 10 steps; otherwise, chunk the steps into subtasks.
5. Keep sentence structures and paragraphs short and simple.
6. To facilitate scanning, bold button names and links that you want the user to click.
7. Include screenshots to identify where things are, especially when it’s not obvious.
8. Use diagrams to illustrate concepts.
9. Use examples and scenarios to strengthen understanding.
10. Avoid unfamiliar terms and concepts (jargon, for example). Always define acronyms first.
11. Add tables of contents with chapters or books that logically organize the content.
12. Choose a readable font for the medium and make the size legible.
13. Balance text with graphics to increase the layout appeal.
14. Include video tutorials directly within help topics to demonstrate confusing processes.
15. Write in the active tense so that it’s clear who is doing what.
16. Ensure steps are accurate, especially after developers near the end of a release.
17. Where applicable, use drop-down hotspots to compress multiple topics on the same page.
18. Single source the material so you can provide both online and printed help to accommodate both learning styles.
19. Insert cross references or hyperlinks in relevant places for more information.
20. Be consistent in your methods so the reader can better follow you from topic to topic.

Nothing I’ve said should be revelatory to any technical writer who’s been hacking away at help for a while. But if you give the same list to developers, I bet most of these techniques never cross their minds. Adhering to these principles would be so tedious and painstaking that it maxes out their writing thresholds.

I’m not saying that if TechSmith help authors adhered to all of the above, they could fit the entire contents of their support forums into their online help file without making it look dense and complex. But to some degree, yes. To some degree, adhering to best practices does allow you to get more information to the reader in a cleaner, more organized, more consummable way, as illustrated by the following graphic.

The more best practices you use, the more info you can deliver to the user in a consummable way.

1. Do research beforehand.

Research is the single most important preparation you can do for an interview. If you’re familiar with the subject, you’ll be able to naturally follow up the interviewee’s answers with relevant questions. You’ll have an informed starting point that will lead to a more natural exchange about the topic.

Neal Conan, host of NPR’s Talk of the Nation, spoke to the Poynter Institute on interviewing. He said,

The most important preparation [for interviewing] I’ve found is to read all the time. We need to be information sharks; either we’re moving and feeding, or we’re dying. (“The Art of the Interview“)

Even if you’ve only glanced at the person’s articles, blog, or presentation slides, the information will present itself to you in the moment you need it. The interviewee will mention a keyword or topic that will trigger your memory (“hey, there were 10 slides on that topic ….”) and help you know the direction you should go.

2. Ask questions based on the interviewee’s responses.

The best interviews resemble natural conversations. If you watch Jay Leno interview his guests, it doesn’t appear as if he has prepared a script of questions or practiced with the interviewee. In fact, it doesn’t even look like an interview — it looks like a spontaneous and natural conversation.

Jim Short, a seasoned reporter, stresses the importance of this type of free-form interview:

If there is an “art” to the interview, mine is free-form. I can’t remember how often, in more than 30 years of reporting, I’ve gone into an interview with one idea or plan in mind, only to come away with something entirely different — and usually more entertaining.

That’s probably my number one rule. Let the interview write the story instead of doing the interview to support your own theory or viewpoint. Obviously, it’s necessary to have a story idea as a jumping-off point, but that shouldn’t be so restrictive that the finished story has an unwarranted slant or offers an inadequate picture of the subject. (“The Interview as Free-Form Art”)

One way to create a free-form interview is to ask questions based on the interviewee’s responses. Exchanges built from answers usually lead to more natural conversations. This will help you move in a direction of discovery rather than proceeding through a list of pre-written questions (which can be stiff).

Joe Hamlin, another journalist, also stresses the same free-form technique when interviewing. He says,

Unless you have an agenda, have three to four questions prepared to get things rolling. Then follow where the subject wants to take you. (“Interviewing Techniques”)

Think of the list of questions you’ve prepared as one possible route through a city. It may not be the best route to take, and there are dozens of different roads to get to your destination. Take the route that attracts you the most. If you get lost, fall back on your original map.

3. Find people who have something to say.

I learned a lot when I interviewed 20 people at the STC Conference in Minneapolis last year: people who don’t have much to say don’t say much. An amazing revelation, I know. But I’ve always held the idea that everyone is interesting, everyone has a story to tell — you just have to find out what it is.

Well, sort of. Everyone may have an interesting story inside, but can you dig it out in 5 minutes? Will they tell it (assuming they know what it is)? I’m still pursuing that ideal, but in the meantime, I look for people who are experts on a topic. Usually they’ve written an article, or presented, or are forum moderators, or hold some leadership position. When you ask them questions, they have something to say. It makes the interview go a lot easier.

I’ve noticed that in Anna Farmery’s The Engaging Brand podcast, she almost invariably finds interviewees who are book authors. And she reads their books prior to interviewing them.

Anna will pick out interesting quotes her and use them as prompts to initiate conversation. She’s an informed interviewer, but her guests are also informed experts on the topics. With that combination, good content flows naturally.

4. Pick topics you’re interested in learning about.

I’m selfish when it comes to topics for my podcast. At least every week someone recommends a topic for the podcast, but if I’m not interested in the subject, I never get around to scheduling it. I use the podcast to learn and interact, and I’m assuming others are like me.

Some topics just don’t excite me —project management, networking, e-learning content management systems. Ouch, you say. Well, those are all interesting topics I’m sure, but right now I’m not focused on any of those things, so I’d rather not go through the hassle of scheduling someone to interview, and then the tedium of processing the audio recording.

I don’t try to find podcasts that are interesting to my audience — I’m trying to find podcasts that are interesting to me. My audience will naturally follow. That’s the cool thing about podcasts — you can tap into a niche audience because the globe is your soundboard.

Doug Kaye, founder of IT Conversations, explains that all content is valuable to someone, even a podcast on the school board of Kuala Lumpur. Whatever your topic, you’ll attract an audience of listeners somewhere.

5. Don’t be afraid to ask tough questions.

Although I shouldn’t, sometimes I refrain from asking a certain question because it might make the person feel uncomfortable. I suspect he or she will regret coming on the podcast. This stems from some kind of indoctrinated politeness. However, it’s bad interviewing practice.

You’ll notice that my interview with RJ was pretty tame. I left out some of the big questions. Part of the reason was that the podcast was sponsored by Adobe. But I’ve found that when I listen to podcasts, I want the interviewer to ask the hard questions.

Ask the questions you want to ask. Your listeners want to hear them, you do too, and most likely the interviewee has the best responses for them. One interview where I did ask the hard questions was with Anne Gentle on wikis. To my surprise, she didn’t choke or stumble on the answers.

If you do have tough questions, Hamlin recommends saving them for the second half of the interview (“Some useful interview techniques”).

6. Let the interviewee speak most of the time.

Even if you have a lot of theories and ideas about the topic, remember that you’re interviewing someone. As I mentioned previously, I come to the interview to learn, to absorb the other’s knowledge. If I’m constantly explaining my own viewpoint and perspective, I might as well deliver a monologue instead. A good rule of thumb is to let the interviewee speak at least 75% of the time.

Actually, when I find myself commenting a lot in the interview, I get the impression that the interviewee has absolutely no interest in what I’m saying. I’m stealing his or her spotlight. I hear a silent voice in my head projected from the interviewee — “Why’d you invite me on the podcast if you just wanted to lecture me.” This shuts me up.

7. Give the interviewee 10 questions to prepare, but don’t limit yourself to those questions, nor the order.

I find that people are more agreeable to a podcast if you give them a list of 10 questions to get started. It’s easy for me because I can think of 10 questions about almost every subject. And it’s easy for the interviewee because they have a starting point to prepare. In fact, giving them questions often piques their interest in doing the podcast.

Based on the person’s answers, you may decide to ask follow-up questions that aren’t on the list (the free-form method described in tip 2 above), or you may ask the questions in the order most relevant to their answers.

The 10 question trick also doesn’t intimidate the interviewee. If you were to give someone 25 hard-to-answer questions for the podcast, they may back out before the interview or continually postpone it.

8. Avoid commenting on their answers.

After the interviewee finishes responding, avoid making empty comments on their responses. Don’t say things like “That’s great,” or “Exactly, so true” or “That’s nice.” Although this may sound innocent in writing, in an interview it can sound stiff. You don’t have to follow up their responses with anything, actually. Just move on to the next question. Or move into your next question using a segue from their response.

9. If interviewing in person, don’t let the interviewee hold the microphone.

Rookie mistake: never let the interviewee hold the microphone. They’ll move it around as they gesticulate. If you listened to my last podcast (with Paul Pehrson), You’ll notice I made two mistakes. First, I held the mic closer to my mouth than his. The Shure SM58 creates a great deep sound when you speak into it one inch away from your mouth. No interviewee lets you do that, unfortunately. Most people have a one-foot safe space with the microphone. Violate it and they move back. The trick is to match the same one-foot distance when you speak into the mic as well — otherwise the audio will be unbalanced.

Second, hold the mic really still. Don’t try to inch it closer to the interviewee, hoping to get better sound. The mic hears every miniscule sound your moving hand makes, and embeds it permanently within the audio recording.

I have a lot of post-production tricks that I do to level and balance the sound, but I’ll save that for another post.

10. Keep everything informal.

As a final note, I hear of some people requiring interviewees to sign contracts related to copyright of their material. For example, Joseph Humbert from the East Bay STC chapter wrote an article in the Dec 07 issue of Tieline describing the need for a written contract:

Besides the hardware and software needed to produce a podcast, we knew we needed a written agreement or contract for both parties—the chapter and the speaker—to sign. Initially, we set a time limit of one year and provided that no money was to be exchanged for the podcast rights. (“Podcasting Speaker Programs for STC Communities”)

I think that’s ridiculous. I do everything on a virtual handshake. There’s no money involved, and if the person ever wants me to retract a podcast, I’d simply do it.

I have edited out parts of a podcast before (insignificant sections based on people’s obsession with sounding right about things). If you whip out a legal contract, it will probably frighten people away. I have more than 80 podcasts on my site and I’ve never had anyone complain about copyright or legal matters.

Conclusion

I’m interested to hear your tips. Am I doing anything radically different from you? Do you have any advice for me?

On a closing note, if you’re nervous about the interview, remember that it’s fun to be interviewed. Sure people may feel jittery at first, and postpone or reschedule the date, but if you’ve ever been interviewed before, it’s an exhilarating feeling. It makes you feel important, an expert. It makes you feel like the whole world is listening to you. It’s an experience people never forget. (Except Thom Haller, who I interviewed once for 45 min, met him at a conference several months later, and learned he had no recollection of me.)

Additional Resources

If you want to learn more about interviewing, I recommend that you read the Neal Conan essay, The Art of the Interview, which I quoted earlier. It’s an excellent read from a veteran interviewer.