I'd Rather Be Writing » Ben Minson

Arguments for and Against Tripane Help

Tom Johnson — Thu, 17 Mar 2011 14:27:43 +0000

My colleague Ben Minson wrote a post about why tripane help is a relic of the book-paradigm documentation age, and how it can limit us from taking advantage of other web technologies. See Why I Don’t Like Tri-pane Help.

As a quick definition, tripane help is the standard webhelp HTML output that has several frames — the table of contents pane on the left, the main topic area in the middle, and a pane across the top. For example, here’s a sample tripane help I created a couple of years ago for WordPress:

This is an example of tripane help. It's all a giant frameset, with the table of contents on the left, a navigation bar across the top, and content in the middle. That's three panes -- hence the name, tripane help.

I agree with Ben’s arguments that discourage tripane help, and yesterday I even wrote somewhat of draft rant titled “Rest in Peace, Tripane Help.” But as it was still in draft mode, I mulled it over. I also listened to a Scriptorium webinar on DITA Best Practices by Tony Self, which helped me see another side of the argument. In this post, I want to present a more balanced argument for and against tripane help.

Cons of Tripane Help

Let’s start with the cons of tripane help.

Hard to modify. Have you ever tried to modify the look, feel, or functionality of tripane help? It’s usually a complicated undergrowth of impenetrable frames and custom code. Hacking RoboHelp’s webhelp, for example, requires you to dive into arcane tips and tricks from sites such as Rick Stone’s RoboWizard, which still looks, with its outer space background, like websites did back in 1995. Rick’s site itself is an example of tripane help.

Rest in Peace, Tripane Help

Flare gives you finite control over the style of each element, but not over the larger structural elements. What if I don’t want frames? What if I want the main search engine on the home page? What if I want the sidebar on the right, with drop-down submenus that slide out? Why can’t I just code it with a separate CSS file from scratch like a regular website, choosing what I float, choosing the behavior of my navigation buttons, etc?

Overall, tripane help is hard to modify because of the extensive frameset and proprietary code.

Looks outdated. Although you can tweak its styles here and there, you can’t make tripane help look like a regular website. It just doesn’t fit in with anything on the web that you find post-2005.

The more we move into the future of the web, the greater the divide grows between tech comm and interaction design. That divide worries me. When people see a tripane help site open up, it immediately signals a sense of outdatedness.

Lacks web functionality. It’s not just about the limitations of tripane help’s look and feel, though. It’s also about web functionality: RSS feeds, comments, embedded videos, lightboxes, jQuery effects, real-time editing, browser-based authoring, built-in metrics, category links, tags and tag clouds, most popular articles, faceted browsing, instant search, search engine optimization, threaded conversations, and so on. You don’t get hardly any of this with tripane help. Ouch.

By confining our HTML deliverable to the rigid tripane help, we become distanced from the forward movement of the web. We become publishers of HTML content but without any of the slick knowledge of web design or interaction design.

Keeps you in book paradigm mode. As Ben points out, we also get stuck in a book paradigm mode, where the only idea we can come up with for organizing our help content is a bunch of topic folders. Ben points out:

One of the limitations of a TOC is that you can display only topic titles. If you set up pathway pages like Redish describes, you can give the reader more guidance. A risk you take with TOCs is that as the user doesn’t find what he wants, he expands more and more books or folders, and he ends up with an overwhelming list of topics. Instead of holding his hand and leading him along, you’ve paralyzed and frustrated him.

In my experience, help authoring tools don’t lend themselves to dynamic Web outputs that allow you set up this kind of guided experience. You could do it, but it’s not supported well out of the box.

Limits your technical creativity. When we get comfortable with a tool that allows us to publish tripane help, we get locked into whatever built-in features and capabilities the help authoring tool allows. Sometimes we can hack in tweaks and other modifications, but it’s usually not worth the hassle. What happens when we want to try leveraging some of the more web-like features to improve our help, such as faceted browsing or instant search? Because we have confined our technical prowess to a specific tool, we’re not equipped to be more creative and innovative with new approaches to help. We become dependent on tool vendors for innovation.

Pros of Tripane Help

Now for the pros of tripane help.

A tripane help output can help us separate content from design. You're free from worrying about matters outside of content. In this sense, tripane help can be liberating. It breaks the chains that hold you back from focusing more on content.

Allows you to focus on content. In the Tony Self DITA webinar, Self stresses that the paradigm of DITA authoring is to separate content from format and design.

In the DITA model, an author creates a standalone topic that is independent of any particular book or format. This standalone topic can be pushed out into any deliverable or any table of contents and stand on its own. Because of this, the DITA writer doesn’t worry about styles or design. The DITA writer can focus on the content, because after all, this is what ultimately matters.

Tripane help allows you to avoid worrying about format and design. You don’t have to consider the details of the CSS and the look and feel of the content in the web output. Someone has already taken care of that. The design has already been created, and you can redirect this effort that you would normally spend on design and apply it to your actual help content (perhaps creating illustrations and other content diagrams, if you still have an itch to design something).

Most users don’t complain about the design of help anyway. They complain about the poor content, right? So doesn’t it make sense to focus on content rather than design?

Allows variety of classification schemes. At first, it seems that you can only create a topic-based hierarchy for your table of contents (TOC) in a tripane help. The tripane help seems to force you into a book paradigm. But this is only convention. You could abandon the traditional TOC approach and instead organize the content by audience, by timeline, by most popular support requests, or some other scheme.

A lot of tools that produce tripane help have tagging, relationship tables, and other techniques for applying non-traditional organizations. In fact, these tools may even make it easier to manipulate the content in alternative ways.

With the robust TOC that tripane help offers, you could build these alternative entry points directly into the TOC, giving users several different ways to navigate the content — by task, by role, by workflow, by popularity, by department, by feature release dates, and so on. Tripane help gives you an easy way to do this, rather than relying on a web team or a JavaScript/interactive designer to help you code these features.

Provides content re-use, localization, single sourcing. Although these benefits aren’t specific to tripane help, using a tool that auto-compiles to a tripane help output usually gives you additional advantages with content re-use, localization, and single sourcing. You can conditionalize content for various role-based, versioned, or beginner/advanced types of guides. You can package all your files up and send them off for translation, and then reimport them. You can single source your content into print and online and mobile deliverables.

Sure, a web 2.0 site looks cooler, but is it worth the sacrifice of content re-use, localization, and single sourcing, which may be much more important for technical documentation needs? All of these additional benefits are usually available if you stick with tripane help instead of abandoning it for a web-based content management system.

Conclusion

One of the potential fixes for the tripane help eyesore, without losing the benefits, is to have the help authoring tool output its content into div tags that you can use to structure and style as you wish. If you can escape the traditional tripane look and generate a more attractive website, you can move towards the best of both worlds.

Unfortunately, tripane help has helped contribute to a growing divide between interaction designers and technical writers. So even if you could structure your output with div tags, most technical writers lack these web design skills. They’ve been limping along with the tripane output for so long that even basic HTML is often an unexplored territory.

Additionally, most technical writers aren’t familiar with any other information architecture techniques outside of basic topic-based hierarchies, so they may not feel a need to innovate with alternative organization patterns.

Blog Sponsors

Finding Time to Draw: Ben Minson at the STC Summit in Dallas, #stc10

Tom Johnson — Mon, 10 May 2010 03:57:31 +0000

Ben Minson and I attended Don Moyer‘s session on drawing for technical communicators. Don explained simple drawing techniques to illustrate concepts. I asked Ben Minson, an artist, to comment on Don’s session and evaluate whether he thinks the techniques would be useful or practical in the workplace.

Blog Sponsors

Day 2 Cartoon [The Twelve Days of Christmas in June Giveaway]

Tom Johnson — Fri, 05 Jun 2009 12:00:32 +0000

Congrats to the winner of yesterday’s contest. (I added the winner’s name at the end of the comment thread of the last post.) Let the contest continue with Day 2′s cartoon, again drawn by the talented Ben Minson of Gryphon Mountain. The winner of this caption contest will receive a free copy of Camtasia Studio, courtesy of TechSmith. For full contest, details, see this post.

Remember, add your caption in the comments below. The winning comment will be announced in the comment thread for the post.

Blog Sponsors

STC Summit Atlanta Adventures: The Agony and Ecstasy of Presenting

Tom Johnson — Fri, 08 May 2009 22:57:34 +0000

STC Summit in Atlanta

This week I returned from the annual STC Summit in Atlanta. Every year is always a series of adventures at these conferences. I’d never been to Atlanta before. I arrived a day early, because I was originally scheduled to give a workshop on blogging, but it was canceled due to lack of participants. Attendance at the STC Summit overall was down by about 35%. I was relieved, however, at not having to put together a long workshop in addition to three conference presentations.

As soon as I got to the hotel, I ran into Alan Houser, the program chair of the conference, who asked if I wanted to eat dinner. I attribute much of my good luck in getting conference proposals carefully considered to the fact that Alan is a long-time listener of my podcasts.

The next day I decided to get some exercise. I’d been reading about a Run-n-Shoot Athletic Center, which had 10 indoor basketball gyms. The concierge confirmed the place existed, even though they never answered their phone. I took a train and then bus out into the West End to find the place. Getting outside the downtown district with all the fancy hotel and conference centers was an eye-opener, reminding me of scenes from the Bronx.

When I finally got to the address, the Run-n-Shoot center had been converted into a fitness center, the gyms converted to bowling alleys and skating rinks and playlands. The only remaining basketball court had a limited court time that ended a few hours ago.

I returned to the hotel and worked on my presentations some more. A couple of years ago, I was converted to a visual-based method of presenting. I hate extended bullets on slides, so my slides consist of nothing more than a title and an image.

To find the right images, I sometimes drag icons from Visio into Illustrator, make a few tweaks, drag them to Photoshop, make some more adjustments, flatten them, and then insert them into PowerPoint. The way I set up my blogging presentation, each slide was supposed to trigger a story, and then I had several points to cover, which I hoped to magically remember during the presentation without having a bulleted lists on the slide. This flexibility allowed me to go with the flow as I presented.

As I looked through the program, I realized that for some reason my presentation was an hour and a half instead of an hour. I only prepared for an hour and wondered when they might have told me my presentation was supposed to be 90 minutes instead of 60. They probably did tell me at some point—long ago—but my email inbox has a constant stream of messages that I often miss. I decided to splice in some tips on blog usability that I’d given in another presentation, just in case.

The Sunday before the conference begins is Leadership day. A few years ago I attended Leadership Day in Minneapolis and was excited about it, since I was a new chapter president at the time. This time around, however, I found my interest anemic almost from the start. Even with the first speaker, I surfed on my Windows mobile instead. It turns out the Society is either $500,000 or a million dollars in debt, and plans to rely partly on chapter finances to make it through. (Since our chapter seems to have an annual budget of $5 anyway, the restricted budget didn’t seem to have much impact, but quite a few people were vocal about it.)

After slipping away from Leadership Day, I returned to my hotel room to work on my presentation, to read more of Gladwell’s Outliers (which had totally hooked me on the plane), and to nap a bit.

The opening keynote by David Pogue the next morning was engaging and completely interesting—not so much because of his message, which was about the power of simplicity, but because of his theatrical, dynamic style. He knows how to deliver a keynote. I was laughing, shaking my head in agreement, twittering about it. The whole place was mesmerized. His presentation skills filled me a bit with dread towards my upcoming presentations, because I knew I couldn’t present like that.

Later that evening, I ran into Kirsty Taylor from Australia. I knew her from comments on my blog and Twitter, but she really is a fan of my wife’s blog, whataboutmomblog.com. She said she had some gifts from Australia for Jane and the kids. This amazed me—that she’d brought gifts all the way from Australia. I know I have a lot of blog readers, but my wife has blog disciples. I later interviewed Kirsty for a podcast, asking her why some blogs inspire devoted followers while others, like mine, simply invite casual attention. Not surprisingly, it’s the personal aspect of the blog, she said. Speaking to the reader’s heart and revealing appropriately, she explained.

When I presented on blogging, the session was full. I found I was able to remember most of what I planned to say, and not having bullet-by-bullet points on slides resulted in a conversation-like style, someone later told me. I breathed well and didn’t run out of content for the full hour and a half. My back started to hurt, though, from standing in the same general place so long.

I’m glad I had the opportunity to present on a topic I’m so passionate about. There are many things I’m somewhat knowledgeable about, but only a few things I’m truly passionate about. Blogging is one of them. My passion for it was apparent, and this enthusiasm made any nervousness disappear.

It seemed that after my blogging session, I ran into people I knew everywhere. Not just people who listened to the session, but people who had been following my blog, people in past chapters, past conferences, people whose blogs I followed, or people I knew from Twitter, and so on. I could hardly walk through a room without running into someone I knew, or encountering someone who knew me and wanted to say hello. My colleagues later told me that I was “amazingly social,” even though I find that comment surprising still.

After my blogging presentation ended, I started thinking about my next presentation—a 20 minute presentation about usability (“What you learn by watching others use your documentation”) in the Usability SIG progression. Usability is not my strength, but I’d given a videocast and written a post or two on the topic, which caught the attention of a SIG coordinator and he invited me to speak at a progression table.

I remembered a video I’d taken of Jane being frustrated at the computer, and I decided to use it to open up a few observations about what users do when they’re frustrated. Mainly, they don’t use help, even when they’re wringing their hands and cringing. I recommended moving the help into the interface, following some pointers Mike Hughes gave me in a podcast months before.

Progressions work differently from normal presentations. About six different presenters have round tables that seat a dozen people. Participants go from table to table, switching tables three times during the hour.

My table was next to some well-known experts in the field—Ginny Redish, Caroline Jarrett, Karen Bachman, Whitney Quesenbury, Chauncey Wilson, and Mary Deaton. Almost every one of them has either written books on usability or works as a usability consultant. When the SIG progression leader introduced me, she said, “And at the back table, we have the famous Tom Johnson …”

I thought this was funny, but it turned out to be somewhat true. It seemed that practically everyone knew me from my blog or podcasts. Even people I didn’t think knew me later added, casually during a conversation, “I feel like I’m in one of your podcasts, listening to your voice.”

My presentation wasn’t outstanding, but I don’t think it was bad either. Some said that overall the progression was the best progression they attended (I’m not sure if the same people actually came to my table). But I have to admit the progression format turns me off a little. It’s noisy. It’s weird. It’s short and seems rushed. Not many other people I met liked the progression format either.

I had one more presentation to give, this one a co-presentation with my Gryphon Mountain colleague about quick reference guides. Co-presentations, I’ve decided, are actually more difficult than single presentations, because you have to make sure the other presenter is prepared and that he or she won’t overlap topics, that your handoffs will be seamless, that you will appear as one rather than switching back and forth in awkward ways.

Also, I was a little concerned because my colleague was fairly new to presenting. He’d never presented at the Summit before, and he had a soft-spoken voice that made him hard to hear. I told him to speak up and avoid slipping into a monotone rhythm. He had a few note cards he used to remember his points on various slides, as did I.

The presentation wasn’t until late in the next day, so we still had some time. While walking about the vendor expo and meeting with people, I ran into incoming STC Toronto president Anna Parker-Richards, who I didn’t know. But as she was talking to me, I asked her about her chapter’s new meeting model, in which they charge $100 to $150 per meeting (or “event”). What she explained—the “Five and Five Model”—was so interesting I decided to record a podcast with her right there. That interview got me in the mood to record other podcasts, and soon I started carrying around my Zoom H4 recorder everywhere.

I interviewed Ginny Redish about her book Letting Go of the Words (which is really about writing web content). I interviewed Caroline Jarrett about her book on forms (Forms that Work) and why forms are important and interesting. I talked with Mike Hamilton about Madcap’s upcoming Flare-DITA solution, to Alan Porter about his book, the History of the Illustrated James Bond (and how James Bond relates perfectly to technical communicators). I talked with Sarah O’Keefe about her latest study on the state of structured authoring. I even spoke with some guy from the Netherlands and his method for prototyping with refrigerator magnets.

Tracking people down for podcasts is mostly a matter of chance. If I ever had a conversation with someone who was particularly interesting, addressing something new, such as a book or study or trend, I pulled out my recorder and asked if I could do a podcast right there. (When it comes to podcasting, I have no reservations about approaching a total stranger and interviewing him or her for a podcast. It makes the conference so much fun.)

Our quick reference guide session was scheduled for 5 p.m. on Tuesday—unfortunately at the end of the day, when everyone is tired. My colleague and I skipped some of the afternoon sessions to prepare. He practiced in the room, saying aloud his parts. On one slide I thought he had too many points for the lack of visuals, so I asked if he could make the commentary during some of the example slides. I rehearsed what I planned to say about design, but had to ultimately concede that, as much as I tried explaining it, design was like music. You could try to describe and explain how it works, but it was slippery and hard to pin down. Designs that work just feel right, regardless of any specific principles.

At five o’clock, the room was packed. No chairs were empty, people stood at the back and sides of the room, and there were even about 7 or 8 people watching from the hallway.

The lapel microphone wouldn’t stick on my colleague’s floppy shirt collar, so he held it in his hand. I buttoned up my shirt collar a notch so the lapel mic would be closer to my mouth. It worked, even if I looked nerdy. The room lacked a wireless mouse clicker, but at the last minute Jackie Damrau (who received a president’s award at the conference) retrieved one from her hotel room for us.

To start the presentation, my colleague began reading, in a funny voice, a cartoon he’d drawn. This made people laugh. Then we launched into the presentation. It went well for about the first 20 minutes, and more and more people started coming into the room. I could hardly believe how popular the session was.

Little by little, raised hands started to appear in the audience. First one hand, and then another, and another. It seemed everyone had questions to ask, which we tried to answer. Some of our answers related to slides to come, but I thought it best to give the answer now, with full elaboration, rather than wait. I think that proved to be a bit of mistake, because too many questions can kill the flow and rhythm of a presentation. For everyone that asks a question, there’s another person that doesn’t want to listen to someone asking a question.

Still, the majority of people remained engaged and interested in what we had to say. The quick reference guide examples provided visual appeal and were practical. My colleague projected well and covered good ground. More than a dozen attendees stayed after to talk to us individually, and for the next day people complimented us on the presentation.

But later in the evening, when we returned to our hotel room and checked the STC 09 Twitter feed, a tweet did provide a bit of a downer, because the person said we needed a moderator, more concrete examples, and that we were more frustrating than interesting. Negative feedback is sometimes hard to take, but it is more instructive in the long run, and I could see how to improve our delivery the next time.

That night, even with the sour tweet, having completed all my presentations, I felt a burden lifted from me. At the same time I wanted to collapse from exhaustion. I went to dinner with my colleagues and a few new friends. I thought a woman who joined us (Trina) had a foreign accent, but she turned out to just be from Milwaukee. Another LDS technical writer from Connecticut (Chris Keeling) joined us. A former drill sergeant and game aficionado, he had a love for his old blind and deaf cat, which he gave an IV to every day, he explained. The cat also drooled on his head in the morning. He and another woman, coincidentally, were both former military intelligence officers who translated Russian, or something.

As the night ticked away, I couldn’t help but feel satisfied both emotionally now that the presentations were over and physically now that I was eating.

After the final conference luncheon the next day, I still had a few more hours to kill. I had a goal to interview ten people for podcasts, and given my theme of recently published books, Karen Bachman recommended I talk with John Hedtke, who has published 26 books, his most recent one on Disaster Preparedness.

This was my first encounter with John. He was articulate and well-spoken. He explained why he wrote about disaster preparedness—”for the money,” he said. I prodded him a little more. Perhaps you had a disaster in your own life that motivated you to explore this topic? I asked. No, he said. I really just wrote it for the money.

While I was talking with him, though, he mentioned that he wrote in the evenings and weekends, after work. You mean you have a regular day job besides your book writing projects? I asked.

Apparently, yes. Computer books (most of what he’s written) have a short shelf-life, he explained. And most nonfiction books don’t make back their advance checks, which are usually between six to ten thousand dollars. Listening to John made me think twice about book publishing.

Regardless of whether I ever write a book, I reflected on the idea for a while in a dreamy way—thinking about possibilities and topics and who might publish it and whether it would be in color or not. Shortly after my conversation with John, I flew home.

Overall, the Summit is always a good experience because it gets me engaged in the profession. It engages me with presentations, which requires my best thinking, organizing, and delivery skills. It engages me with podcasts, interviewing people on the spot, drilling deeper into their knowledge. It engages me with new ideas through sessions from experts and authorities in the field. And it engages me with a new environment, surrounding me with new friends and a new city. It is a short stretch of time, about four or five days, but its effects last throughout the year.

By the way, this year all presentations (except the progressions) were recorded. You can buy the presentations from the STC (called Summit@aClick) for a price (no one knows how much yet). I’m told that I can also post my own presentations on my blog for free, which I’ll certainly do when they’re available.

If you enjoyed this writeup, see my write-ups from previous conferences:

Blog Sponsors

STC Presentation this Thursday: “Quick Reference Guides: Short and Sweet Technical Documentation”

Tom Johnson — Wed, 25 Feb 2009 07:09:59 +0000

This Thursday, my colleague Ben Minson and I are presenting to the Intermountain STC chapter on “Quick Reference Guides: Short and Sweet Technical Documentation.”

Here’s a description of the presentation:

Users often want documentation in a format that will give them the basics and get them on their way as fast as possible. Not all technical communication situations will benefit from quick reference guides, but almost every user rejoices at the site of one-page documentation.

Despite the brevity of quick reference material, the thought process involved in creating, organizing, and laying out the content is time-consuming. This format requires you to right-size content and decide the most important information the user needs to know. Additionally, you must describe with extreme concision and clarity processes that usually require dozens of pages to explain.

Beyond strategies for quick reference material, we will also review several tools, such as Adobe InDesign, that can be used to create quick reference guides. We will present feedback we have received from users and project managers that highlight the benefits of the quick reference format.

Sound interesting? Delivering quick reference guides will win you more praise than almost anything else you can do as a technical writer. In our presentation, we’ll walk through ten sample quick reference guide templates, pointing out elements of design that make them work (or not work).

Here are the meeting details:

Location: Downtown Salt Lake City library, Utah
Time: 7:00 p.m.
Cost: Free
Food served: Light fruit and cheese, and maybe a brownie

For more details, such as driving directions and the library location, see this PDF flyer.

By the way, if you have a quick reference guide template that you’d like to share, send it to me at tomjohnson1492@gmail.com. My colleague and I are also presenting on quick reference guides at the Summit in Atlanta. I’d like to collect as many contrasting quick reference guide layouts as possible.

Additional Resources

I’ve previously written a couple of posts on quick reference guides:

Blog Sponsors

Leaning Towards Longer Topics and Shorter TOCs

Tom Johnson — Tue, 23 Sep 2008 04:36:09 +0000

Everyone knows it’s a good practice to chunk your help material into discrete topics, but how granular should you chunk it?

Take a look at this Microsoft Word 2007 help topic on inserting headers and footers.

Example of a Quick Menu from Microsoft Word's Help on inserting headers and footers

Although inserting headers and footers is the main task, the topic really has 11 related tasks:

Insert the same header or footer on each page
Make the first page header or footer different from the rest of the pages
Use no header or footer on the first page
Make the header or footer different for odd and even pages
Make the header or footer different in each section or chapter
Change the contents of a header or footer
Insert a page number
Insert the file name of the document
Insert the document title, author’s name, or other document property
Insert the current date
Remove the header or footer

The author could have created 11 separate topics. Do you agree with Microsoft’s decision to group all of these subtasks into the same topic? Or would you rather explore each subtask as a separate topic in a table of contents?

Although the practice of single sourcing encourages chunking of tasks, if you won’t be reusing the subtasks or related tasks independently, there’s little reason to separate them out into discrete topics. Forcing all of these subtasks into separate topics would severely bloat the table of contents (TOC), rendering it not only less usable, but also more intimidating. Your application’s apparent complexity would magnify.

Separating each subtask into its own topic often forces users to click in a non-linear pattern from topic to topic as they search for the right task. This nonlinear clicking can give users a headache. It’s part of the reason why reading online is more strenuous than reading a book. Books provide more of a hierarchical layout and logical progression of ideas. In contrast, the web is a scattered maize.

Consolidating subtasks into one topic also improves the user’s ability to find topics. With fewer topics in the TOC, the user can actually browse the TOC and find the right topic. But even if the user reverts to keyword searches, the longer topics will have greater keyword density and more likely rise to the top in search results.

I sent a question across Twitter the other day asking whether anyone had done research into this issue, and Brenda Huettner pointed me to a Web Usability Guidelines reference book. Chapter 8 echoes Brenda’s response that “it depends.” The authors say that older people are slower at scrolling, but comprehension may be better because the user remains on the same page. Here’s an excerpt:

Guideline: Use longer, scrolling pages when users are reading for comprehension.

Comments: Make the trade-off between paging and scrolling by taking into consideration that retrieving new linked pages introduces a delay that can interrupt users’ thought processes. Scrolling allows readers to advance in the text without losing the context of the message as may occur when they are required to follow links.

However, with pages that have fast loading times, there is no reliable difference between scrolling and paging when people are reading for comprehension. For example, one study showed that paging participants construct better mental representations of the text as a whole, and are better at remembering the main ideas and later locating relevant information on a page. In one study, paging was preferred by inexperienced users.

Sources: Byrne, et al., 1999; Campbell and Maglio, 1999; Piolat, Roussey and Thunin, 1998; Schwarz, Beldie and Pastoor, 1983; Spool, et al., 1997; Spyridakis, 2000.

In other words, each time a page loads, you interrupt the user’s thought process. By remaining on the same page, the user can better grasp the concept as a whole.

Thanks for the resource, Brenda! In the studies, the content consisted of web pages rather than help material. Some of the examples for scrolling depict long, sophisticated pages — quite a bit more hairy than the Word example above. Still, I agree with the general findings and think they apply to help authoring.

My colleague Ben Minson, however, raises an important objection to long topics. He says,

In reality, people don’t want long topics. They want to think that procedures are short and simple. Long topics intimidate people and make them reluctant to consult the documentation in the future. (“Long Topics: A Help Author’s Crime Against Humanity“)

I agree that no one wants to be confronted with a massive topic when all they need is information to complete simple task. However, adding a quick topic menu at the top, similar to the following image, seems to solve that problem, doesn’t it? The user can jump immediately to the relevant topic, rather than meticulously scrolling down and checking each heading.

[image title="Example of a Quick Menu" size="full" id="2017" align="left" linkto="viewer" ]

Overall, in my experience, it’s easy for a help’s TOC to grow successively larger as you think of more and more scenarios, possible tasks, and concepts to explain. But if you reach the end of the project and see that your initial 50 topics have grown to 250, I think something’s wrong. Most applications aren’t that complicated. When users expand the TOC and find a seemingly infinite number of topics, it’s the equivalent of the disheartening “thud” from a long printed manual.

Guest Post — From Blogging Veterans: Three Keys to Successful Blogging

Tom Johnson — Sat, 12 Apr 2008 03:36:06 +0000

The following is a guest post by Ben Minson, one of my technical writing colleagues. Ben’s blog, which also focuses on technical communication, is called Gryphon Mountain Journals. Check it out. (You can subscribe to his RSS feed here.)

My wife recently bought a book for me entitled Blogging Heroes: Interviews with 30 of the World’s Top Bloggers. Blogging has been around for about ten years now, but one blogger said in this book that he thinks blogging is still in its infancy and has a lot of potential. If you’re thinking about blogging, that’s good news.

One of the questions that the interviewer, Michael Banks, typically asked each blogger is what advice he or she had for other bloggers or for people thinking about starting. With the range of advice you’d think could come from 30 people, so far there are three main themes or pieces of advice that characterize the answers.

Key 1: Blog about Your Passion

I heard this from Tom himself before I started blogging, so this wasn’t news to me. But the question “What should I blog about?” probably runs circles around in every prospective blogger’s head. It’s the same answer to “What should be my major in college?” The answer is to pick the thing that makes you tick and go with it.

The “heroes” also advise you not to set out to make money. If that’s your goal, it’s going to be obvious, and you’re going to turn people off. They’ll know you’re interested only in their money rather than in expressing ideas and encouraging discussion. One of the things that turns me off of Web sites in general is when I see more ads than content. I don’t like having to wade through commercials to get to the meat of things. Some people expect ads, but for the vets, advertising (if they have any) came after the blogs were well established.

Generally, your passion is what you know. So write about what you know. It will be more natural if it’s something you can talk about with enthusiasm and understanding.

Key 2: Reward Readers for Visiting

The main rule here is to produce quality content. Don’t post just because you think you need new content every day or every other day. Give your readers something of value. Of course, what is one reader’s treasure trove is another’s garbage pile, so realize that what appeals to some may not to others. But if you personally think a subject isn’t worth the time it takes to click the “Publish” button, don’t write about it.

Next, write well, or at least the best that you can. A blog fosters frequent writing, but if you recognize shortcomings or errors in your writing (or others point them out), do what it takes to improve.

Allow open discussions about your posts. Be respectful to those who comment, even if they sound overly critical. At work, we have a list of “cultural beliefs,” or guiding philosophies specific to working in our department. One is “speak up”—give honest and respectful feedback. A corollary to this that I have heard, though not one of the official beliefs, is to “make it safe” to speak up. We ought to try to receive feedback graciously, even if the feedback hurts. Your readers aren’t going to visit your blog if you respond to their comments with criticism or insults. Further, don’t just encourage users to make comments, but use them to improve yourself.

Key 3: Don’t Beg for Traffic

The vets don’t all encourage posting comments on other sites, but they suggest that if you do participate in discussions, don’t do it just to get traffic. Contribute meaningfully to the conversation. It’s obvious when you’ve posted a comment just to draw attention to your own blog. That kind of comment may get blocked by administrators, but if it doesn’t, looking like a beggar won’t reflect well on your site or what you have to say. Participate on others’ blogs meaningfully, and they’ll be more interested in drawing attention to your blog.

You’ll notice that I’m guest-posting, which is one way to generate traffic. I didn’t ask Tom to do so—I didn’t even think of it. He offered, and I appreciate the opportunity to stand on the I’d Rather Be Writing stage for a day. Don’t take for granted any such opportunities that you’re given, and don’t put across the idea that you’re doing the hosting blogger a favor by posting on his blog.

How Do You Measure Success?

Opinions may vary on what success means for a blog. Some would say that success is making enough money from a blog that you can do it full-time. Others may say they’ll consider themselves successful when they have a million readers. For many of the bloggers interviewed in Blogging Heroes, success is providing content that connects with readers. Success is giving readers something valuable to think about and discuss, some way to make their voice heard, and a source of information or answers to questions that they may have really needed. If you write with these goals in mind, your blog will be more satisfying, and the million-dollar deals and million-reader audiences just may come along on their own.

Ben’s blog | feed

——————-

To write a guest post for I’d Rather Be Writing, send me an email letting me know.

How to Get Your Blog Mentioned in the Society for Technical Communication’s Intercom: Include the Word “Technical Communicator”

Tom Johnson — Sat, 05 Apr 2008 04:14:42 +0000

“Technical Communicator” is a term that, as much as I dislike, can be extremely important for triggering Google Alerts set up by the Society for Technical Communication‘s Intercom editorial staff.

How do I know this? Well, a couple of months ago I saw a summary of my blog post on video cameras and SMEs mentioned in the STC Intercom’s Cut & Paste section (shown below).

(Direct link to Intercom article above.)

My original blog post wasn’t really that interesting and, after discovering Jing, I would in no way use a video camera in place of Jing.

But that’s no my point here. My point is, how did the Intercom editors at the Society for Technical Communication come across my blog? Are they regular readers? (Of course, everyone should be.) I shrugged my shoulders and didn’t think more of it.

Then a couple of weeks ago, my friend Ben Minson, also a technical communicator, mentioned that a post on his blog — “When Tech Writers Don’t Read Directions” — caught the attention of Intercom editors as well, and they asked to publish an excerpt in Intercom.

How did they discover Ben’s blog, which is less than a month old?

I asked departing assistant Intercom editor Cecily Waters for insight on exactly who is keeping up with the blogosphere at STC headquarters. She said that the managing editor of Intercom has Google Alerts set for the words “technical communicator” and “Society for Technical Communication” and some other phrases.

With those keywords in mind, let’s take a look at an excerpt from Ben’s post:

The common perception that all technical writers do is produce instructional manuals isn’t totally undeserved; after all, that is where the profession got its start. While the field of technical communication has branched out considerably, a technical communicator’s job still involves giving directions of some sort. … I violated the Unspoken Rule myself twice this week in regard to the Society for Technical Communication.

The keywords that set off the Intercom editor’s Google Alert no doubt included technical communicator, technical writer, technical communication, and Society for Technical Communication.

(By the way, you can set up your own Google Alert here. I used have a few alerts, and they were actually quite accurate, especially if you’re trying to track mention of your name or blog.)

When I write posts, I often change the title to reflect a more search-engine-optimized phrase by using the WordPress SEO plugin. Keyword optimizing your first and second paragraph with the same keywords increases the SEO even more.

Now you know the keywords that trigger alerts to the Intercom editor, currently Ed Rutkowski. In fact, if I had a unique name like Ed, I’d also set a Google Alert on that too.

Given the keywords I’ve spread all over this article, this post will probably trigger one of Ed’s alerts. So Ed, if you’re reading this, be sure to drop me a line and say hi.

How to Get Everyone and Their Dog/Family/Friends Reading and Subscribing to Your Blog — 10 Tips

Tom Johnson — Sat, 29 Mar 2008 06:34:04 +0000

Just a few days after someone begins blogging seriously, he or she starts hungering after subscribers and comments. We want readership, we want lots of people visiting our site, reading our posts, subscribing to our feed, and regularly leaving comments. This, my friend Clyde says, is the “payoff” of blogging.

Although I try to write for a higher purpose outside of trying to get more readers and comments, I must admit that the interactivity of blogging is what makes it fun. To this end, I offer ten tips for increasing your readership:

Be patient. My friend Ben Minson is just starting out with his Gryphon Mountain blog. He currently has 4 subscribers, but he’s been writing excellent posts for the past 2 weeks, and he’s starting to get noticed. My wife has a witty, fun-to-read blog (whataboutmomblog.com), but only has 51 subscribers. To people who get discouraged at a lack of subscribers, I say be patient. It takes time to accrue readership. I have ~~471~~ 472 posts on my blog.
Use Twitter and Twitter Tools. Twitter is the most surprisingly useful tool I’ve seen. I’m starting to check it almost as much as Google Reader. When I publish a new post, through the Twitter Tools plugin, that post is automatically published as a tweet on Twitter. Lots of cool people (e.g., Robert Scoble, Darren Rowse, Chris Pirillo) will follow you on Twitter if you start following them. Check out the Twitterati here. But really, you want to follow people like yourself. Through your tweets, they’ll pay closer attention to you and your posts.
Search-engine-optimize your posts. My site stats show about 65%+ traffic from Google. Google finds you by matching keywords that searchers use with keywords for your site (obviously). Pack your titles with search engine keywords. And use the WordPress SEO plugin to differentiate the title your readers see from the title Google sees. For example, this post’s Google title is more generic: Increase Subscribers to Your Blog — Tips for Increasing the Number of Readers. Boring, I know. But it’s the kind of string people search for. I want to be found.
Link abundantly in your posts. People check you out when you link to them. We’re always curious to know the contexts in which we’re being mentioned. The pingback brings people to your site, and if you look interesting, they subscribe. You’ll notice I’ve linked to everyone I mentioned in this post. Linking to people is like tapping them on the shoulder to get their attention.
Make intriguing titles. I find myself reading posts with interesting titles (for example, Dear WordPress, A Response to Your Letter). Even when the post is outside my category of interest, I’ll click a clever title out of curiosity. Copyblogger also has excellent advice about titles. I think learning to create intriguing titles is an important art in drawing readers in. (Holly Harkness reminded me of this lately.) Don’t worry so much about keywords and use the WordPress SEO plugin I mentioned in #3.
Catch the attention of people with influence. If you catch the right people’s attention, they can mention you on their site and boost your readership far more than you can alone. One of my earlier posts caught the attention of Joshua Porter (Bokardo), and overnight my readership grew by 80+ new subscribers. Some of the people I interview for podcasts (e.g., Anne Rockley) mention the podcast to their large readership base as well.
Use the Feedburner chiclet to watch your readership. I don’t watch site stats as much as readership stats. I’m convinced that good posts will naturally attract new readers. If my readership shrinks, I know my writing stinks. If it grows, it’s because the posts must somehow be worthwhile. People naturally link to interesting posts, which grows your readership. Without Feedburner, I don’t see how you can measure readership at all. (By the way, the numbers always artificially dip on the weekends. I am still inching toward my 1,000 mark.)
Leave comments on other blogs. I always check out the blogs of those who comment on my posts. And I try to leave comments on posts I enjoy reading, if only to let the person know that I read it. Commenting on as many blogs as possible is a tedious strategy for gaining readers, but when you’re new, you need make yourself visible. No doubt you read blogs already, so add a comment. Other commenters are also attracted by an interesting comment you leave, which leads more people back to your site.
Write a few home run posts. The best post I’ve ever written was 20 Usability Tips for Your Blog: Condensed from Dozens of Bloggers’ Experiences. It has 293 comments and trackbacks. I spent weeks writing it — it was the core of my presentation at least year’s Doc Train conference. It is certainly my home run post. Everyone has a home run post inside them. Rhonda’s is a little post about blueberry muffins, which has surprisingly attracted thousands of hits. When you write it, your readership will take off.
Write useful content. A vague assertion, I know. But if your information isn’t useful, practical, or somehow noteworthy and interesting, no one will subscribe. Part of the appeal of sites like Lifehacker and The Blog Herald is that they provide useful information.

Bonus Tip: If you want quick exposure, write a guest post for my blog. Simply contact me and send me either your post or an idea for one.

photo by cogdogblog