February 2008 | HelpScribe

Full text search vs. keyword search

Lately I've been pondering whether users are better served by full text search, such as the search functionality in most web browser help formats, or a human-edited keyword search with ranked results.

Full text search

The full text search results in many help formats can be overwhelming to users. In a large help project, users could easily be presented with 50 to 100 topic titles, all listed alphabetically. How do they decide which is most relevant?

Are users likely to scroll through such a large set of topics, clicking anything that sounds promising until they find an answer to their question?

Full text search, however, does offer a complete set of results. If a single obscure reference to the search phrase is buried in the bottom of the topic, users will be able to find that topic in the results.

But is a complete set of results the most helpful format for a majority of users?

Keyword search

What if the majority of users could find their answers faster by clicking a ranked list of results, similar to Google? Keyword search allows help authors to present what we think are the topics most likely to answer the majority of questions for a given search term.

If a user searches on "printing reports," chances are the "Printing reports" procedure is going to provide the answer, right? So shouldn't that topic appear at the top of the list of search results?

Keyword search can be tedious to set up. It requires indexing your content and studying past user search data. But maybe such an effort is worthwhile if more users find what they are looking for in the help.

A combination of both

Eventually I think help authoring tools will offer a combination of full text search and ranked keyword search to appear in the same help system. (Adobe, MadCap, are you listening?) That way we can present users with a few promising topics that will likely answer their question, followed by a complete list of topics for the users who are looking for less predictable instances of the search term.

Essential technical writing authoring tools

Not all tools are created equal. Some technical writing authoring tools have proven themselves to be key industry standards that have stood the test of time and put tons of quality documentation in the hands of users. These are the tools that should appear on your resume, and that should be on your hard drive if you want to produce great documentation using feature-rich tools.

Help Authoring Tools

RoboHelp - In spite of its dramatic past (see "The king is dead!"), RoboHelp is still the tool to beat when it comes to authoring help. Whether you are delivering web browser help or locally-installed CHM files, RoboHelp delivers. Adobe's dedication to improving the product has been impressive and RoboHelp just keeps getting better.

Flare - The only real alternative to RoboHelp. When Macromedia neglected RoboHelp, much of the development team left to create Flare, and many technical writers followed. The Flare team added innovative enhancements such as support for variables, a highly customizable interface, and an editor that provided new ways to view content. Also, the MadCap team has assembled a lineup of products that can compete with the Adobe tools.

Word Processing Tools

FrameMaker - Frame shows up in just about every technical writer job description I see. Why? Because its ability to handle large documents without corruption, render page layouts in a consistent and intuitive manner, and fit into a structured authoring workflow make it an essential tool for writing manuals.

Word - Word has entrenched itself as a viable alternative for technical manuals simply because it is installed on almost every business machine in the world. Sharing and reviewing documents is much easier when everyone in the company has the same software installed. And features? Word is packed full of them. If FrameMaker isn't in your budget, or if you don't need to handle large, structured documents, rest assured that Word is probably going to get the job done.

PDF Publishing

Acrobat - Acrobat is clearly the leading PDF tool on the market, having started the PDF format in the first place. The Adobe Reader is free for everyone to download, and most of us do. 'Nuff said?

Those are the essential technical writing authoring tools that most of us have installed.

If you are looking for a complete package of tools, check out the Adobe Technical Communication Suite.

The authoring tools listed above are especially essential if you are a contractor who frequently works on documents produced by others, or if you are starting a new technical writing team. (You can't go wrong by choosing time-tested tools.)

Some may argue that the list needs a screen capture tool, a demo tool such as Captivate, or an image-editing tool. Perhaps. However, I think many of the tools on the market would work just fine for such tasks.

Free tools

If I was a new technical writer trying to get started on a budget, I'd likely take the free tools route. Free authoring tools have come a long way, and in most cases are robust enough to compete with proprietary tools. These tools would allow a new writer to produce a full set of documents and learn the production process without spending a dime.

Here's what I'd install...

Task: Word processing

Tool: Open Office

Open Office contains a full office suite, including the excellent Open Office Writer. Writer is packed full of useful features and looks and feels much like Microsoft Word. It can convert your documents to PDF without Acrobat. Also, Open Office uses XML as its native file format, making future portability a breeze.

Task: Help development

Tool: Microsoft HTML Help Workshop

The Help Workshop compiler allows you to import HTML files and build a fully functional HTML Help system. It has tools for creating a Table of Contents and Index, and robust help for guiding you through the process. You can save any RoboHelp vs Flare worries for later, when your budget isn't so tight.

Task: XML editing

Tool: Cooktop XML

Cooktop is an "under the hood" editor, not the WYSIWYG variety. However, it has robust editing features, syntax highlighting, and allows you to specify an XSLT file for transformations.

Task: HTML editing.

Tool: Nvu

Nvu offers tabbed editing, WYSIWYG view, FTP and publishing tools, and other robust features to compete with the big guys. If also boasts full support for XML, JavaScript, and CSS. What else could you want from a free HTML editor?

Task: Graphics editing

Tool: SerifPlus 4.0

This free version of SerifPlus supports numerous file formats, easy-to-use wizards, and some really great drawing tools. And you can always upgrade to version X2 if you want to shell out some cash for the latest features.

That's it. Those are the free tools I'd use to learn the publishing process and create professional quality documents on a shoestring budget. Obviously you'll want to reconsider this toolset when your budget increases, but these free authoring tools will get the job done.

Improving the review process with wikis and project management tools

How often have you had the following experience?

You send an important document out to reviewers... they respond with conflicting edits. You follow up with them via email to resolve the open issues... and they reply with more conflicting edits.

Then you run around in person trying to get some answers they can agree on only to find one of your reviewers has left for vacation.

This is when you start reconsidering your career and thinking seriously about that taxi driver position in Siberia that you turned down.

Why reviews are tedious

Let's break down the problem.

Reviewing in print doesn't allow reviewers to compare notes or see each other's edits.
Electronically routed reviews do not allow the first reviewer to see what the last reviewer has changed.
Often the wrong people are included in reviews.
Scheduling issues make it difficult to receive all reviewer comments in a timely fashion.

Wow. That's a lot of headaches.

A better approach?

Reviews don't have to hurt. Wikis and web-based project management tools can address most of these issues.

Wikis, as well as the document repositories in web-based project management tools, allow reviewers to log in and view your document in its current state.

If a reviewer makes some changes, they can log in again later to see how those changes were impacted by later reviews. They can make more edits if they wish. The latest version is always available.

The discussion tab in a wiki or web-based project management tool allows reviewers to communicate about suggested changes. All issues are resolved right in the open for anyone to see. This eliminates the need for the writer to act as a moderator. You may still need to ask reviewers to clarify something or come to a consensus, but you can do so from the comfort of your office chair and trust that everyone had equal opportunity to respond.

Deadlines are helpful. Tell your reviewers to log in and make their changes, discuss any issues amongst themselves, and come to a conclusion by the end of the day (or whenever) so that you can finalize and publish the document. A wiki takes the pressure of the writer by giving reviewers the tools they need to come to a consensus.

Wikis and project management tools also make it easy to include all relevant people in the review. Anyone with access rights can log in and participate, and a firm deadline will keep even a larger number of reviewers on task.

You'll still have some difficult issues to resolve now and then. For example, if your SME is on vacation and can't log into the wiki, you won't get a review. But wikis and project management tools can take a lot of the pain out of the review process.

How to improve your help by mining user forums

User forums can be a real gold mine for finding topic ideas to round out your product's help. Often such forums receive an incredible amount of traffic. Why? Because they give users quick answers that help them complete specific tasks.

Think about it. Most users are trying to complete a specific task using your product. They don't want to dig through reference documentation to find the details. If a user can't start his lawnmower, why put him through the misery of an overview of the internal combustion engine?

A forum, however, is like asking, "Hey Carl, what's wrong with this lawnmower," and hearing "Ain't got no gas in it."

Problem solved.

Here are some ideas for turning forum conversations into help, so your users can find the answers they need right away.

Monitor recent posts

Check forums regularly for new posts. When you see one, look at the number of users who have viewed the post. Is it high compared to other posts of roughly the same age?

If a new post is receiving a lot of traffic, search your help to see if you've provided an answer already. If so, perhaps you need to revise the title so that it more closely matches the post title. Users may not be recognizing your help topic as an answer to their problem.

Write new FAQs and procedures

If the help doesn't address the issue discussed in the post, it's time to create some new help topics.

First, write a short and highly focused FAQ with a title similar to the post title in the forum. Don't argue with the evidence; the high post traffic tells you the post title is essentially on target. Clean it up, but make sure users would still recognize your topic as addressing their issue.

For conceptual problems (e.g. "Does the Date of Birth field require a 4-digit year?") a FAQ alone might be sufficient. If the forum post suggests a few steps, you should draft a procedure.

The post itself will outline the essential steps of the procedure. You'll just have to organize and edit the long-winded conversation into something elegant and more usable. When your procedure is complete, create a link from your new FAQ to your procedure.

Make your answers easy to find

Now that you have some tightly-focused topics to offer, make them easy to find. Here are some tips for doing so.

Organize your FAQs into a list categorized by subject matter so users can quickly navigate down to the more granular topics.
Make sure your FAQs can be searched from Google, not just your help viewer.
Put a checkbox next to the forum's Search field that says "Include product documentation in search results." Many users will prefer a well-written FAQ to a user conversation once they realize an official answer exists.
Ask the team responsible for maintaining the forum for a report of search keywords entered by users. When you know what phrases users are searching for, you can write your help topics appropriately.

Follow these tips and your users will soon have a greater respect for your help. They'll find the answers they need quickly without having to scroll through confusing or inconclusive forum conversations.

Why wikis won't kill technical writing

Many people have predicted that wikis will replace traditional help in the future. Ok, I can buy that.

But I've also heard that technical writers will surrender content control to SMEs and users, and will move into other roles such as merely editing wiki content, or switching to programming, training, etc.

Sorry. I just can't see that happening.

In the world of wikis, technical writers will still be kings of content. Here's why...

Organization

If you've ever read through wiki or forum discussions between users or SMEs, you're probably aware that unorganized information is not user friendly. A usable wiki must have an intuitive structure. Technical writers will likely fill that role.

Information architecture is one of our primary skills, and a technical writer or help author will have an existing knowledge of how to organize the documentation because of previous experience organizing help and print content.

Extensive cross-referencing will also require a technical writer. A user or SME may think to link to a related procedure, but it will be a technical writer who replaces that single link with a comprehensive set of cross references so that it is helpful to a wider number of users. In fact, the writer will likely reformat an existing set of related links taken directly from the help. Extensive cross referencing would be difficult to anyone without a big-picture view of the documentation.

Generating content

Will users write helpful troubleshooting content? And will SMEs be better equipped to verify that the content is accurate?

Absolutely.

But will either bother to provide comprehensive documentation, such as a complete set of installation instructions or system requirements? How about an introduction to the product for new users?

Not likely.

A single user or SME won't usually have the time or inclination to do so. Users are more interested in answering task-related questions. Developers have higher priorities, such as improving the product itself. SMEs may review content, or provide chunks of information related to their individual component of the product, but aren't likely to spend time writing comprehensive instructions or providing cohesion between their content and information from other SMEs.

Technical writers, on the other hand, are devoted to the documentation. They have the information-gathering skills to turn unrelated chunks of notes into something that won't leave readers scratching their heads.

Managing the documentation

The best wikis will be written by technical writers, with tactful references to user forums when appropriate. Reviews and conversations with SMEs will be delegated to the Discussion pages of the wiki. Technical writers will then finalize that information by moving it into the Guide section of the wiki, so that users don't have to wade through a meandering jargon-filled conversation that may or may not provide any useful information.

The Guide section of the wiki will be locked down to filter out noise. Login will be required. (For example, see the Blender wiki. New writers need to request editing privileges and work with an existing author, and new content is sandboxed.) A documentation team will still be necessary to manage the wiki, just as they managed the old help and print content.

In short, technical writers will be doing the same job we always have. We'll just be using a new tool that offers some very promising features. We'll have improved communication with both users and SMEs. Everyone wins.

Will technical writers delve into programming, training, usability, and other tasks? Sure. But we've always had to wear lots of hats, haven't we?

At the end of the day we'll still call ourselves technical writers.

Related:

Simple ways to improve usability of help

According to Jacob Nielsen's How Users Read on the Web, usability of web content can be improved drastically by making content more scannable. Many of his ideas would apply equally well to online help. So, how can technical writers leverage this information to make the help for their product more usable?

Use granular topics

Long reference topics and procedures should be broken into smaller, granular topics that users can scan. Often users lose confidence in the help because they cannot find the information they are looking for, even when the information is present in the topics they are viewing. It just isn't presented in a format that is easy to digest.

Break your topics down into smaller chunks and users will have a better chance of spotting the information they need.

Add subheadings and mid-topic jumps

Use meaningful subheadings and mid-topic jumps to allow users to quickly scan for and access the content they seek. Don't make them read through long topics packed with information that is unrelated to the task they are trying to complete.

Use a flowchart

Graphics are much more scannable than text. For complex procedures, provide a flowchart to help users quickly grasp the overall process. Link each step in the flowchart to a related procedure.

Organize your table of contents

If your help includes a table of contents, be sure to structure the table of contents so that it accurately reflects the organization of the help. The table of contents serves as a conceptual map of your help. An accurate map will help users quickly find the content they seek.

Step out lengthy procedures

Use a numbered list for procedures instead of stringing together sentences, and limit each step to a single task (or a couple of smaller tasks).

Users access the help when they are stuck. They may already be half way through the task described by your procedure. By stepping out procedures into smaller, scannable steps, you allow users to quickly jump into the procedure at the appropriate step to complete their task.

Use bulleted lists whenever possible

If your help contains lists of features, prerequisites for a task, or other list-type information, be sure to format the content appropriately. A bulleted list is more scannable than sentences in paragraph format. Also, each individual bulleted item will stand out to users, thus decreasing the possibility of a user overlooking any single item.

Emphasize when appropriate

Be judicious in your use of bold and italics. Too much of either will decrease the overall impact and distract users from the content that is really important. Use bold or italics for emphasis when it matters most.

Link related topics

Hyperlinks are one of the most useful features of online help. They also make your content easy to scan.

Use hyperlinks carefully to take users only to content that is related to the task they are trying to complete. The overuse of hyperlinks is not only a distraction, but it also can take users away from the very content they seek. Be careful when including them in the middle of a topic. Put related hyperlinks at the bottom of the topic, so that users aren't steered away from important material.

Hopefully these tips will improve the usability of your help, and allow your users to quickly scan for and find the information they need.

If you enjoyed this post, you might also like:

22 tips for writing software documentation users will actually read

Writing software documentation is much like juggling porcupines while walking a tight rope in 50 mile-per-hour winds. Your attention is constantly divided and the situation is always changing. The moment you finalize your work, a new feature appears in the software, and you find yourself scrambling to document it in time for the product release.

So, how do you go about writing technical manuals for software without going insane?

Here are some guidelines you can follow to maintain your sanity when writing software documentation.

Create and maintain a style guide. Style in technical writing can vary from one product to the next, and you'll save yourself a lot of grief by keeping notes regarding conventions.
Keep your friends close and your SMEs closer. If you can promote open and frequent communication with developers, writing software documentation will be much easier. You won't be blind-sided as often by changes in the software.
Install often. Don't waste time writing software documentation for an out-of-date version of the product.
Make time for testing. Be sure to try out every procedure at least once to verify that the instructions are accurate.
Talk to the Support staff. You'll be more effective at writing software documentation if you understand the problems users typically experience.
Use templates. Have a template for each topic type (reference, FAQ, procedure, etc.) and use them for quickly fleshing out new topics. You can find detailed document templates here.
Invest in your tools. A feature-rich set of technical writing authoring tools will make the process of writing software documentation much smoother. A help authoring tool, such as Adobe RoboHelp or MadCap Flare, and a tool for print documentation, such as Adobe Framemaker, will suffice. Some XML-based authoring tools are capable of producing both printed documentation and help.
Invest in your skills by learning from others. If you run into problems while writing software documentation, open up the MadCap Flare help or an Adobe RoboHelp manual and see if they've tackled the same situation. Find examples of great technical writing and emulate them.
Stay organized. Learn to use project management software to track pending tasks and notes. Keep a manila folder for each project and fill it with printed copies of notes and important email messages. This is especially important when writing software documentation for multiple products at once.
Keep a list of questions for SMEs. Your time with them will be more productive, and they will appreciate your respect for their busy schedules.
Focus on your help navigation, table of contents, or index. There's no point in writing software documentation that users can't find. Enable full-text search, if possible.
Prepare use cases, and compare your procedures to those use cases. Does your documentation cover all of the tasks your users need to complete? If not, fill in the missing content.
Be specific. When writing software documentation you must be particularly clear about tasks the user must complete versus tasks that the software completes automatically. Ambiguous language will leave users scratching their heads or reaching for their telephones to call Support.
Provide context. Writing software documentation isn't just about telling users what to do. You must also tell them why they would want to complete a task, and explain the desired outcome. This point is particularly important for anyone using a single-sourcing methodology where chunks of content are combined to create the final output. Be sure to provide context to show how those chunks of content are related and create a feeling of continuity.
Verify that your documentation set is complete. Did you include accurate installation instructions? How about contact information for Customer Support? Does your product warrant a tutorial or interactive training? Writing software documentation often requires producing more than just a printed manual or online help.
Leverage existing content. If your company provides a knowledgebase or support website, refer to it in your manuals. Use cross-references to guide users through all of the various forms of product documentation in an intelligent manner.
Use a consistent design for your documentation. Users will adapt to your design and learn more effectively if you present content in a consistent and user-friendly manner.
Delete unnecessary content. Writing software documentation isn't like writing a novel, and brevity will often result in improved clarity. However, don't leave out important information for the sake of being brief. Use as many words as necessary to accurately explain a concept, and no more.
Find peer reviewers. Preferably, get another writer and a product developer to review your documentation. They will help sort out any technical inaccuracies, and improve the clarity of your writing.
Revise often. The great thing about writing software documentation is that you usually have frequent opportunities to deliver updated content. Developers constantly ship newer versions to include the latest features. Take advantage of those updates and ship your latest improvements to the software manuals and help.
Set some informal deadlines for yourself. Factor in time for documentation reviews, testing, and dealing with troublesome authoring tool issues. One of the difficulties of writing software documentation is the instability of product release schedules. By maintaining your own aggressive deadlines, you'll be more prepared if the company decides to ship the product two weeks earlier than planned.
Have some fun. Play network games with the developers, or go out for a long lunch with your fellow technical authors. Writing software documentation is hard work. Don't burn yourself out.

I hope these tips make the process of writing software documentation a little less painless. If you're as crazy as the rest of us technical writers you might even enjoy it!