Examples Are a Primary Way That Complicated Concepts Become Clear

In my recent poll about why users can't find the answer to help, one of the top answers (so far) is the lack of examples: The help doesn't provide concrete examples that make the concepts understandable. (View total votes.) I've long been a fan of examples in help documentation, but I didn't suspect they played such a large role. In fact, one rarely hears any presentations or reads blog posts on using examples. It's time to give this t...

Interactive Poll: Why Can't Users Find Answers to Their Questions in Help?

I'm preparing for an upcoming presentation at a local STC chapter in the SF Bay area. I'm hoping to get some feedback before I finalize this presentation, so if you have some ideas, I'd love to hear from you. Here's my draft: Why Users Can't Find Answers to Their Questions in Help Content One of the main goals of help material is to help users find answers to their questions, but so often this doesn't happen. Users foray into the help ...

Why I Test Nearly Everything

One of the forms of writing I like most is the essay, which is a form that has strong origins with 16th-century Michel de Montaigne. Montaigne saw essays as a kind of attempt or test of an idea and his judgement about it (see Montaigne's Moment). Since I like the essay format, it's not surprising that I also like to test content. In fact, testing content constitutes one of the main characteristics of good technical writing. By testing con...

When Organizing Big Data Content, It's Okay To Be Messy

I recently listened to an O'Reilly programming videocast interview with Travis Lowerdermilk about his new book, User-Centered Design: A Developer's Guide to Building User-Friendly Applications. During the videocast, Travis notes that according to Jakob Nielsen, you need only 5 users to identify most of the problems with a UI design. Lowdermilk acknowledges that the idea has been challenged by some, including Jared Spool and others (see Wh...

7 Ways to Learn Difficult Subjects in Order to Write Useful Content

Since I switched jobs about 6 months ago, I decided that I wanted to move toward writing developer documentation. Not only is the job market for this skill extremely hot, it's also a challenging and interesting landscape to explore. I'm currently writing a lot of code samples for a JavaScript SDK. Even though I'm comfortable with CSS, HTML, and a lot of technical topics, like designing and developing WordPress sites, I've had to ramp up o...

Turning Around the Disdain for Help by Focusing on Content

For a long time I pursued findability as a solution to fixing the documentation problem. But lately I've been less persuaded that findability will solve documentation's ills. Instead, I'm become convinced that what's really wrong with help is the content itself, not necessarily allowing people to find it. Why? Because "it" often doesn't exist. The user is trying to find something that hasn't been created. What's really wrong First, a quic...

Messages from Sponsors -- July 2013

Etteplan | Tedopres Etteplan | Tedopres releases HyperSTE 5.0 with support for ASDSTE100 Issue 6 and new authoring applications HyperSTE 5.0 is a major update introducing support for new authoring applications, including Madcap Flare and Oxygen. In addition, HyperSTE now fully supports Issue 6 of the ASD-STE100 specification. What is new in HyperSTE 5.0: Full integration of the ASD-STE100 Issue 6 specification. Now also compatible with: ...

Sample Chapter from Word Up! How to Write Powerful Sentences and Paragraphs, by Marcia Riefer Johnston

Marcia Riefer Johnston recently published Word Up! How to Write Powerful Sentences and Paragraphs (And Everything You Build from Them). I had a chance to read an early draft and provide feedback. I really enjoyed the book, so much that I agreed to appear in a promo video: I gave a short quote in the "Advance Praise" section of the book, noting that Word Up is "Light, fun, and enjoyable to read. Marcia approaches grammar and style with a...

Finding a Starting Point: Answering Questions or Addressing Purpose?

Since I wrote my post about how help needs to be more engaging/appealing to users, I've been mulling over a better approach to help. I'm convinced that one key to creating good help is producing the right information. In my last post, I wrote about the need to answer the user's question as the foundation for creating good help. But then I was reading something Mark Baker wrote about addressing purpose instead of answering questions, and I...

Abandoning the Social Network and Q&A Idea

A few weeks ago, I added some social network functionality (Buddypress) to my site as well as a Question and Answer module. You can read about the features here. Unfortunately, the social network plugin added about 5 seconds of load time to my site, and despite my attempts to speed it up, Buddypress is just slow. Caching plugins seem to pose problems with Buddypress, too. The Q&A plugin required user registration to work well (registr...

How do you answer every user's question?

In my last post, I reflected on the most successful experiences I've had in connecting with users and decided that a foundational principle for successful user help is to answer the user's question. I also realized that if there's been a transformation in the user experience of help at all in the past 50 years, one that has had a positive impact on the user experience, it's this: you can type a question into Google and find an answer. The...

What Have Been My Most Successful Experiences in Connecting Help Material with Users?

In an earlier post (Do We Need a New Approach to Help?), I surfaced concerns about the approach to help material in general and asserted that despite 50 years of innovation, most users still have the same reaction towards help: they dislike it and find it a chore. Lots of commenters agreed that we need to create more engaging user experiences. Laura Palmer added that converging instructional design with information design can be a useful ...

Notes from Future of Technical Communication Webinar

Larry Kunz's recent webinar, The Future of Technical Communication, is one of the best webinars I've listened to recently. Larry's message is not only on target and insightful, he also articulates concepts in a clear, organized way. It's easy to listen to and you'll get a ton of useful information out of it. Larry mentioned several trends in tech comm and then several skills tech writers can develop to meet those trends. The following are...

Recording of "Video Tutorials for User Assistance" (UA Europe Presentation)

Listen here: Download MP3 (right-click, then Save Link As) PowerPoint Slides PDF version This is an audio recording of a presentation I gave at UA Europe in June 2013. Here's the description: Next to Google, YouTube is the second most popular search engine on the web. The popularity of video, especially for how-to scenarios, suggests that it should play a more prominent role in user assistance. However, creating vide...

Recording of "Making Content More Findable When Users Browse and Search" (UA Europe Presentation)

Listen here: Download MP3 (right-click, then Save Link As.) PowerPoint slides PDF version of slides This is an audio recording of a presentation I gave at UA Europe in June 2013. Here's the description: Users tend to search Help material when they have a specific question they're looking to answer. In contrast, users tend to browse Help material when they don't know exactly what they're looking for. Browsing often lea...