I'd Rather Be Writing » content

Messages from Sponsors — January 2012

Tom Johnson — Mon, 30 Jan 2012 15:06:06 +0000

Below are a few messages from my blog’s sponsors. Check them out and see if any interest you. Many of them have upcoming webinars.

News from Madcap

MadCap Software is pleased to present free live webinars from industry experts covering a variety of topics essential for today’s technical writers. Sign up today to advance your professional skills and learn about the latest trends in technical communication.

Moving from FrameMaker to Flare | Feb 7, 10:00-11:00 am (Pacific Time)

Are you using FrameMaker as your primary authoring tool? While Frame is great for book publishing, it requires separate tools and plug-ins to single source content for the web. If you are tired of the expense and the headache of using multiple tools, consider switching to MadCap Flare.

Flare matches and exceeds FrameMaker’s best features, including variables, snippets (equivalent to text insets), conditions, and versatile cross-referencing formats. And Flare doesn’t restrict you to a linear, book-based model. You can manage content at the topic level and build multi-sectioned, double-sided books or websites and knowledge bases. Your choice.

Join Eddie VanArsdall as he demonstrates how you can adapt your FrameMaker workflow to a full-on, single-sourcing solution with one tool: MadCap Flare.

Presenter: Eddie VanArsdall, Content Strategist / Technical Writer

Making Your Content Mobile | Feb 23, 10:00-11:00 am (Pacific Time)

This webinar will provide an industry overview of moving different types of content to the mobile environment. Specifically, it will cover developing the following for the mobile environment: (1) HTML content, (2) PDF documents, (3) WebHelp, (4) e-books, and (5) e-learning courses.

Join Nad Rosenberg as she discuss technical issues, usability, and legibility as well as unique problems and solutions.

Presenter: Nad Rosenberg, President, TechWRITE, Inc.

Importing Microsoft Word Files into MadCap Flare Projects | Mar 19, 11:00-12:00 pm (Pacific Time)

Need to import Word files into a Flare project but you’re not sure what Flare’s Word import options do? Or why old and, apparently, well-behaved Word files give odd results when imported into Flare? This webinar addresses both questions.

Flare has a powerful set of Word import features that let you automatically break Word files into topics on import, specify style equivalents between Word and Flare (called “mapping”), and more.

Join Neil Perlin, MadCap-Certified Flare and Mimic instructor and consultant, in this webinar that walks through the process of importing Word files into Flare. We’ll look at the mechanics of the process and discuss the kinds of problems that occur in Word files and what to do to fix them.

Presenter: Neil Perlin, Flare Consultant, Content Strategist, Mobile Developer, Hyper/Word Services

For more information on our live and recorded webinars, please visit:

http://www.madcapsoftware.com/demos/webinars.aspx

News from Dr. Explain

Dr.Explain 4.5 Automates Help File Creation

Unique to Dr.Explain is its innovative approach to creating help documentation much quicker than with other tools. The program parses a live application and automatically produces screenshots of its windows along with a sequence of explanatory callouts for each control.

Watch the video press release about new features of Dr.Explain 4.5:

Annotation Template Editor is one of the coolest new features of the new release. It allows to create callouts of any design, complexity & style. Now you can prepare amazing annotated screenshots and graphics and insert it into your help documentation in a single tool. Dr.Explain produces documentation in the HTML (on-line manuals), CHM (MS Windows® help files), RTF, and PDF formats from a single source.

More information on Dr.Explain: http://www.drexplain.com.

Download a free trial: http://www.drexplain.com/download/. A free license for reviewers, editors and bloggers is provided on request.

News from Scriptorium

Thinking about content strategy? Check out Scriptorium’s latest webcast recording:
http://www.scriptorium.com/2012/01/webcast-content-strategy-in-technical-communication/

Coming attractions:

January 31: Webcast on trends in technical communication with special guest Char James-Tanny
February 15: Webcast on HTML5 with guest presenter Peter Lubbers
Week of February 22: Simon Bate presents at tcworld India; Sarah O’Keefe presents at Intelligent Content

Review the entire events list

News from Tedopres

We are doing a few webinars in the next few weeks.

Join our FREE webinar on Simplified Technical English
Clear & consistent content can help you save cost & improve your customer experience

Tuesday, January 31, 2012
4:00 PM – 5:00 PM EST

Visit Tedopres.com or register at https://www3.gotomeeting.com/register/510570974.

Join us for a Free Webinar to learn about STE Tools
Reaping the benefits from your Simplified Technical English implementation.

Tuesday, February 21, 2012
4:00 – 5:00 PM EST

Visit Tedopres.com or register at https://www3.gotomeeting.com/register/604631086

Provide your end user with the right information at the right time.
How you can use Augmented Reality and make your product information interactively available on an iPad. Read more at http://tedopres.com/HyperSIS-Service-Information-System.

News from Adobe

Switch from MadCap Flare, Author-it, or Doc-To-Help Enterprise, or Doc-To-Help for Word and save 40% off Adobe RoboHelp 9!

Struggling with you current Help Authoring Tool? Looking to “switch” to a tried-and-tested tool that has been the professional standard in the user assistance space for the last 20 years? Adobe has the answer … and the perfect reasons too!

Adobe celebrates the 20th anniversary of RoboHelp with a limited period 40% off “switcher” promotion. Switch from MadCap Flare, Author-it, or Doc-To-Help Enterprise or Doc-To-Help for Word and save 40% off Adobe RoboHelp 9!

Time frame: October 17th 2011 through February 16th 2012
Scope: US only

For more details (top reasons to switch, testimonials, switching resources) about the RoboHelp 40% off “switcher” promotion, see the following:

Saibal Bhattacharjee
Product Marketing Manager
Adobe Systems Inc.,
saibal@adobe.com

Tom Deem
Business Development Manager
Adobe Systems Inc.,
tdeem@adobe.com

Blog Sponsors

Looking at Breadcrumbs in a New Way

Tom Johnson — Fri, 06 Jan 2012 04:09:04 +0000

One of the findability features in our help systems that we often overlook is the breadcrumb. Breadcrumbs typically sit above the page title and highlight the hierarchical path that leads to where you are. Here’s a screenshot of a typical breadcrumb, taken from Adobe Illustrator’s help:

Greg Nudelman discusses breadcrumbs in one of his chapters in Designing Search: UX Strategies for eCommerce Success. This post mainly details notes from Nudelman’s book.

One problem with breadcrumbs, Nudelman notes, is that “breadcrumbs cannot show customers where to could go next. They show only where they’ve already been” (p. 199).

Nevertheless, Nudelman says the breadcrumb aligns with a search/browse pattern that supports common finding practices. Nudelman cites a presentation by Peter Morville called “Search & Discovery Patterns,” where Morville explains that “browse and search work best in tandem… The best finding interfaces achieve a balance, letting users move fluidly between browsing and searching.” (p. 203-4)

In other words, when looking for content, users prefer to search and browse, browse and search. Users perform a combination of the two as they try to find what they’re looking for. This is because, Morville explains, “what we find changes what we seek.” For example, search results for your initial query might show you the correct terms, which then informs your next search.

Breadcrumbs are powerful tools because users can easily modify the breadcrumb path to browse the information they want to see. Nudelman explains,

Providing the ability to change attributes while automatically retaining all relevant query information turns the breadcrumbs into a powerful and flexible finding mechanism, without making the resulting interface overly complicated or difficult to use. (p. 210)

For example, in the above screenshot, I may not want instructions for creating a drop-shadow effect. But rather than returning to the raw search and formulating a new query, I can click the Special Effects breadcrumb and browse the other special effects available. The breadcrumb allows me to modify part of my search without starting over from scratch. Nudelman says users would rather salvage part of their search and refine it rather than starting over:

In my research, people seldom want to start the query over completely from scratch, unless they specifically indicated this action. Instead, a vast majority of the people interviewed wanted to retain as much of the query as possible with every change of the facet values and desired the system to help them construct a query that “makes sense,” gracefully dropping facet selections that no longer applied to their modified query. (p. 208)

One problem with breadcrumbs in most webhelp system is that they perpetuate the myth that content lives in just one place, which is not necessarily true. Content in the digital space can appear in many different arrangements and paths.

Nudelman notes that Edmunds.com’s search results show tag selections as breadcrumbs.

I would like to see webhelp move away from a single hierarchical organization of content to one that simply shows tags that are stacked together in the query. This shift would be a new paradigm for the way help is organized. In Edmunds.com, each of these keywords is metadata for the content. There may not be an official hierarchical order to the content, like there is most webhelp systems. The order is dynamically generated based on the metadata you select.

I recently wrote about tags as being more of a web-based method for classifying information. See Using Tags to Increase Findability.

For more information about Greg Nudelman, see his site, Design Caffeine.

Blog Sponsors

On Content Strategy and Identity

Tom Johnson — Fri, 01 Jul 2011 20:00:36 +0000

A couple of months ago, I realized I would be playing a larger role in web publishing at my work, moving more towards a user awareness role. Realizing this direction, and knowing I had some budget, I decided I should attend Confab, the first conference on content strategy. It was sold out, but by a stroke of luck the organizer offered me one of thirteen tickets held in reserve.

I never wrote much about the Confab conference. In part I was too busy with a presentation and workshop I was preparing for the STC Summit, which was the following weekend. But like most conferences, Confab turned out to be interesting and thought-provoking. This conference brought together experts from many disciplines. I even ran into seven colleagues from my own organization who I didn’t even know were going to the conference.

Developers, interaction designers, writers, marketers, and project managers were all drawn to this conference because they were faced with content challenges they hadn’t encountered before. This conference was the only one that seemed to address the growing issue of content — the common factor behind everyone’s attendance.

Except for a few tech comm notables, there weren’t many other tech writers in attendance. With all the cross-sectioning of disciplines, though, at one point I wondered who I was professionally. I was more than a technical writer. I had taken on web and wiki publishing roles at work, and this only aligned more with my blogging/podcasting/wordpress consulting role outside of work. I didn’t quite know who I was or where I should be anymore.

Later, as I met many people, I also began to realize that marketers and communications people made up the majority of the attendees (at least of those I met). This made me wonder if content strategy had grown out of marketing and the need to address the scope, need, and importance of web content.

I also began to realize that many of the exchanges on my blog I’d had prior to the conference about what content strategy is and isn’t were foolish. From the breadth of the Confab presentations, content strategy encompassed nearly everything related to content. One person defined it as anything you do to give your content an edge. This could be a simple as focusing on story, or defining a particular style and workflow for copy (such as Groupon does), or leveraging metadata and the semantic web, or using strategies for content curation, or infusing web copy with the right tone (“messaging”).

After the conference, I wasn’t quite sure what to make of it all. But I found that I kept searching Twitter for the hashtag #contentstrategy. The articles and discussions around #contentstrategy seemed to be a relevant hashtag that aligned with my professional responsibilities. Publishing, metrics, styles, curation, workflow, messaging — all of this becomes relevant when you’re creating content on the web. And no previous title, such as writer or web manager or information architect, seems to address all the aspects of content that people who publish on the web must take into account.

The shifting of identities that I felt during the conference was the beginning of a larger tectonic shift as I move closer to #contentstrategy. I recognize that many tech comm professionals implement content strategy within technical communication, and certainly Rahel Bailie has been exceptional at defining this influence and perspective within technical communication. But it seems to me that content strategy for the web is an easier fit for this emerging discipline.

The Confab conference ended registration two months early when they hit their attendance limit. I’m guessing that next year, Confab will be an enormous convention, with so many speakers and attendees that it will take the initial momentum of last year and dwarf it in size.

I do not think I’m the only one checking #contentstrategy on a daily basis. Kristina Halverson, the conference organizer, noted that five years ago, you could search for content strategy and find nothing. Today, many new articles, links, and discussions about #contentstrategy saturate the web. Clearly, as I found, content strategy is a term that many are finding aligns with their identity.

——————–

Post update: As soon as I published this, I just saw Waving not drowning: or how I gave in and learned to love the content strategy flood.

Blog Sponsors

WordPress Workshop Outline for the STC Summit

Tom Johnson — Sun, 15 May 2011 06:55:22 +0000

Tomorrow I’m giving a four hour workshop on blogging and WordPress at the STC Summit in Sacramento. I thought I’d post my outline in case anyone is interested in how I approach these workshops.

In preparing this outline, I realized that my focus on WordPress and blogging has shifted more towards producing content rather than manipulating the technology. Several years ago, you had to be more techie to make adjustments to your theme and get plugins to work. Now, the technology has matured to the point where you really don’t have to dive into code. You can just focus on content. However, it has now become more difficult to create content that stands out from other blogs, since new blog posts saturate the world on a daily basis.

WordPress Workshop Outline

1: The Intrigue – Should I start a blog?

Reasons for starting a blog
What you can expect in return
Realistic time commitments
Why blogging is a perfect opportunity for writers

Practice: Share your intrigue with blogging and evaluate your expectations.

2: Setting up the Scene – How do I get set up?

Choosing a web host
Installing WordPress
Configuring basic settings
Adding sidebar widgets

Practice: Set up several WordPress sites. Add various widgets to your sidebar.

3: The Initial Euphoria of Posting – You mean I can post anything about anyone at anytime?

Selecting a focus
Branding the focus on the blog
Publishing a post
Editing the post

Practice: Find the About page on a popular blog and evaluate it. Publish a test post.

4: Getting Trendy with Design – How do I make my blog look cool/professional?

Introduction to themes
Finding good themes
Themes with elaborate backend interfaces
Making manual adjustments to themes

Practice: Install a new theme. Adjust some aspects of the theme.

5: Writing for the web – Why aren’t people reading my long posts?

Structuring content for online reading
Creating links
Linking to other posts
Search-engine-optimizing your content

Practice: Create a link to another post with specific anchor text.

6: Comments! – Why am I getting spam?

What to do when no one comments
Dealing with spam
Activating Spam filters
Responding to comments
Implementing threaded comments
Responding to mean comments

Practice: Install and activate antispambee. Evaluate comments to identify spam.

7: Making it easy to subscribe – How can I get a thousands of readers/followers?

Measuring and track your readership through Feedburner
Making subscription buttons prominent
Pushing content to Twitter and Facebook
Adding the right hashtags to Twitter
Offering email subscription on your content

Practice: Burn your feed and add the Feedburner RSS and email links to your site.

8: Experimenting with Multimedia – What else can I create besides text?

Creating a videocast
Creating a podcast
Embedding a video
Creating a screencast
Inserting images
Working with image galleries

Practice: Embed an image with a caption. Create a gallery. Embed a Youtube video.

9: Blogging for your company – Should I be my company’s blogger too?

Not as fun as you might think
Content curation strategies
Time commitments among other responsibilities
Platform compromises

Practice: Read your airlines’ blog and assess why it is or is not appealing.

10: Making money – This is taking a lot of time. How do I make money to justify it?

Amazon Affiliate links
Google Adsense
Sidebar advertising
Promotion of a product or service
Career leverage
e-books

Practice: Add an ad to your sidebar. List 3 companies who might be willing to place ads on your site.

11: Writing compelling content – What can I do to create posts that make an impact?

Telling stories
Danger zones with personal and corporate sensitivities
Having an opinion
Being insightful
Resting and rereading before posting

Practice: Decide on a story you can tell for a post. Share it with others.

12: Running out of ideas – I’ve run out of ideas to blog about. Now what?

Read –use Instapaper
Write about what you’re doing
Content curation
Collaborative posts
Guest posts

Practice: Mine Twitter for hashtags to identify a good post related to your blog’s niche.

13: Running out of time – Where do I find the time to post to my blog?

Staying up late, losing sleep
Speeding up posting with Press It.
Combining your current goals into your blogging efforts.
Recognizing everyone has content overload already anyway
Maintaining motivation despite crickets

Practice: Use Press It to post a link and excerpt from another blog.

Blog Sponsors

When Help Content Is Forgotten

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

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

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

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

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

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

Two Types of Content

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

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

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

Different Content, Same Question

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

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

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

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

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

Brainstorming Ideas

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

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

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

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

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

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

Conclusion

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

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

Blog Sponsors

Podcast: Finding and Creating Relevant Content — Strategies for Social Media

Tom Johnson — Fri, 08 Oct 2010 06:21:18 +0000

Download MP3
Length: 70 min.

In the barrage of information created by all the social media channels, how can you find relevant content? How can you move past forms of noise to actually produce content that engages users? What forms of social media do students respond to the most? These are some of the questions we explored in a presentation I gave to Brigham Young University Provo students earlier this week. This podcast is a recording of the presentation.

The podcast is about an hour long, and I bookended the presentation with some thoughts before and after.

Blog Sponsors

Students Contemplate Whether a Technical Writing Career Will Be Fulfilling

Tom Johnson — Thu, 30 Sep 2010 14:41:47 +0000

For the past couple of years in October, I’ve gone up to Brigham Young University Idaho to talk to students at their professional writing conference. I’m going up there again this year. In preparation, I asked my colleague who teaches there whether students still think of technical writing as a sellout/fallback career, or whether they’re more seriously preparing for an actual career in technical writing. My colleague responded:

They’ve chosen professional writing as a career because doing so is prudent (or at least more prudent than choosing creative writing or college teaching). They may wonder, however, whether they can really be happy in a career as a technical writer. The professional world is a bit of a mystery to them, and they wonder whether they’ll really end up content as professional writers. They sort of feel that they’ll never know this until they try it, but that after they try it, it’ll be too late to go back and do something else. There’s a sense of entering a career path sort of half blind. Anything you could do to answer whether they could really be happy in a career as a tech writer would help them out a lot.

I’m at a loss for how to respond to this student dilemma. How do you know whether technical writing is the right career path for you? I’m really hoping you can shed some light as to how I could help students resolve this dilemma.

A student contemplates whether a career in technical writing will lead to a fulfilled/content professional career

In previous collaborative posts, I created a Google doc to collect the responses, but in the last collaborative post, most people just added comments below the post itself. The latter method seems more practical. I appreciate any insights you may have.

Blog Sponsors

From Help Authoring Tools to Web Tools, Especially Wikis [Organizing Content 12]

Tom Johnson — Thu, 03 Jun 2010 14:39:49 +0000

Yes, I am continuing this series on Organizing Content, so if you are tired of it, check back in a while. My goal is to reach 100 posts on the topic.

An Electricity Fast

First, a brief bit of news. All the lights in my house are off because Jane wants to do an electricity fast. It’s a Thoreauvian experiment to see what you gain when you give something up. For the past couple of days I’ve been moving about with a candle, or staring at a computer screen in total darkness. I can’t cut off all electricity because that would be a little too extreme — food in the refrigerator would go bad, my side job with WordPress consulting would tank, my blog would slow to a halt. We made agreements about certain allowances. But by merely turning off the lights, it’s amazing how this puts you into a rhythm (or would if I were to turn the computer off).

Time to Take the HAT Off

Back to the topic at hand. In my last post, as I diligently looked into SEO and the importance of help’s visibility in Google, I found that help authoring tools have poor SEO. This is partly due to frames, partly due to the fact that few users will link to help content, and also because HAT code isn’t architected in an optimal way for the web.

If we plan to keep step with the web, we have to use a web platform. As a general trend, I think help authoring tools are going to fade because (a) they do a terrible job at SEO, (b) help authoring tools are poor at collaborative authoring, (c) help authoring tools fail at social media and interactivity, (d) help authoring tools don’t leverage the plugins and extensions of web platforms such as WordPress, Drupal, and Mediawiki, and (e) help authoring tools are expensive compared to web tools.

Additionally, the importance of single sourcing the long print manual is becoming less of a demand (have you handed someone a 100+page manual lately that someone accepted with eagerness? ) I predict that in several years time, we’ll see a major shift towards web-based tools in tech comm, especially wikis.

As a final nail in the coffin, check out this video on social media. It argues that social media presents the biggest shift since the Industrial Revolution.

After watching this video, it seems unlikely that the traditional HAT will be the default tool for software user instruction in a few years.

On to Wikis

Until now, I’ve explored ways to organize content with the assumption that we’re using a help authoring tool. Now I would like to shift to the same discussion but with a web-based platform in mind: the wiki.

Wikis pose serious challenges when it comes to content organization, because all you have are essentially links. In describing different information architecture patterns, Donna Spencer calls wikis a flat model. With wikis, you often don’t have a table of contents feature to organize your topics. You have a page that links to another page that links to another page ad nauseum.

Which Wiki?

Given that there are more than 100 different wiki platforms, it will be difficult to generalize about wikis, because surely some wiki out there (for example, Confluence) probably has a fine TOC feature that collapses and expands. Other wikis may not have flat structures (for example, SharePoint’s wiki system, which provides you with metadata and views). But I will take as my example the quintessential wiki plaform: Mediawiki. (Wikipedia uses Mediawiki as its wiki engine, in case you didn’t know.)

A Maze of Chaos

A few years ago, at a Doc Train West conference, I interviewed someone who asked to remain anonymous. It’s the only anonymous podcast interview I ever conducted (out of about 130 podcasts). The next day, the person asked me to not publish it. Why? The conference had a lot of sessions about wikis. The interviewee explained that at her work, they had created a wiki. It started out okay, but it soon degenerated into a maze of chaos. It had become an embarrassment, an impossible black hole of content. She was cautioning against wikis.

Part of the problem with organizing content on wikis is lack of control. As soon as wikis become a collaborative effort, with multiple authors, the organization becomes much more challenging and is likely to suffer from inconsistency and chaos. I don’t know if this is inherent in collaborative authoring projects, or if it’s inherent in the wiki architecture, but eventually wikis become so disorganized that search becomes the only method of navigation.

Case in point, check out the WordPress Codex. If you have a body of information this size, there’s no clear way to organize it. You end up with links that you can kind of group together, into Getting Started, Design and Layout, Advanced Topics. But then you also have general groupings under vague topics like Working with WordPress and About WordPress. There’s no clear path through the content.

Wiki Categories

One way to organize wiki content on Mediawiki is through categories. Many people reading Mediawiki wikis don’t realize this, but each page is usually tagged with a category. For example, the Wikipedia page on Technical Communication is labeled with the category Technical communication (scroll to the bottom to see it).

The category label appears at the bottom

Categories on Mediawiki work just like categories on WordPress, except that the method for adding them is less intuitive. Somewhere on the page, you just add the text [[Category:Technical Communication]]. This creates a category link that will pull together all other Wikipedia pages tagged with this same category, as shown in the image below:

All topics in the Technical communication category on Wikipedia

This method of content organization isn’t bad, except that the category link is buried in the page’s footer and is practically invisible. Some Mediawiki skins display the category link more prominently.

Still the Same Challenges

Despite this system of categories, you still run into the same issues of content organization. If you click the Discussion tab for this Technical communication category page, you see the following exchange between users:

Does Category:Specification languages really belong in this category?—iFaqeer (Talk to me!) 04:25, Nov 30, 2004 (UTC)

I’m not totally sure. I’m still trying to get my head around how this category system is supposed to work. I think there’s definitely some connection between technical communication and spec languages (like UML) but I don’t know whether it belongs as a subcategory. It certainly looks strange to be all by itself. If you’d like to remove it, I wouldn’t object. –LeeHunter 23:06, 30 Nov 2004 (UTC)

I don’t think it needs to be a subcategory. Perhaps it belongs as a link from an article discussing how some technical writers deal with them in their day to day jobs. Maybe as part of the main Technical communication article??–GeoffPurchase 04:33, 2004 Dec 1 (UTC). The contents of Specification language don’t quite co-relate with the contents of that category. Does it? I mean, do they? The category seems to list what I would call “mark-up languages” while the definition is for a kind of programming language (which might be a superset of what is in the category). If I am right, the latter is definitely TC-related; the former is only marginally so.

I am not very well-informed on either of the two areas my confusion spans, so I would like someone else to chime in. And the reason I keep posting this here is that it’s kinda lonely at Category talk:Specification languages.—iFaqeer (Talk to me!) 05:12, Dec 1, 2004 (UTC)

Does specification language fit into the Technical communication category? Maybe. I’m not even sure what a specification language is. Strangely, when I looked at this more closely, specification language didn’t make it into the Technical Communication category. But Specification did.

Categories and Subcategories

The fun doesn’t stop here. Each category can also have subcategories. Or looking at it from another perpsective, each category can also be grouped under a parent category. When you’re looking at a category, such as the Technical Communication category, scroll to the bottom to see which parent category it belongs to. You’ll see that Technical Communication is categorized under Written Communication | Communication | Technology. Technical Communication is a subcategory for these categories.

Larger categories that Technical communication is grouped under

If you click these parent categories, you’ll see that they’re also grouped into higher-level parent categories, namely, Human skills | Information systems | Language. Human Skills is a subcategory of Skills | Humans | Human behavior. Humans is a subcategory under Anthropology and Hominina. Hominina is a subcategory of Apes. Apes is a subcategory under Primates. Primates under Mammals. Mammals under Vertebrates | Tetrapods | Synapsids.

Vertegrates is a subcategory under Chordates. Chordates is a subcategory under Animals | Phyla. Animals is a subcategory of Life | Natural Sciences. Life is a subcategory of Nature | Phenomena | Fundamental | Main topic classifications. Nature is a subcategory of Main topic classifications | Fundamental. Fundamental is a subcategory of Articles, and then it goes to Content > Parent Categories > Categories > and Contents.

The exact taxonomy depends on how you climb up the topics. Like a pedigree chart of ancestors, you can take multiple paths. But here’s the general layout of categories and subcategories. I bolded the path I took to climb up to the highest level of categorization:

Contents
Categories
Parent Categories
Content
Articles
Main topic classifications | Fundamental
Nature | Phenomena | Fundamental | Main topic classifications
Life | Natural sciences
Animals | Biology
Eukaryotes | Zoology
Animals | Phyla
Chordates
Vertebrates | Tetrapods | Synapsids
Mammals
Primates
Apes
Anthropology | Hominina
Skills | Humans | Human behavior
Human skills | Information systems | Language
Writing / Communication
Written communication / Communication / Technology
Technical Communication

I don’t know about you, but I feel a special pride in the way this plays out, and how in just a few levels, you move from Technical Communication to Chordates. Maybe this is why the Category label appears at the bottom of the article and search appears at the top.

At the Highest Level, Categories Fail

It’s especially interesting to look at categories at the highest level: Contents.

One of the highest levels of categorization on Wikipedia

At this level, content is grouped into such general categories that it’s almost useless — categories by status, by topic, by function, by association, by type. If you were starting out here, would you ever drill down into Technical communication? It would take a miracle. But at the lower, more specific level, the category model does seem useful.

Blog Sponsors

Things Fall Apart, The Centre Cannot Hold [Organizing Content 3]

Tom Johnson — Mon, 17 May 2010 14:27:33 +0000

Let’s fast forward a year. Assume you have explored Swordfish and have hammered out a lot of help topics — nearly 200 help topics, in fact. You have met with subject matter experts and extracted critical information from them for many months. You have explored Swordfish inside and out, documenting every possible task and setting, and now you have a ton of content.

The help topics you created seem endless. You have checked their accuracy against the constantly updated Swordfish interface, and you have made a seamless flow from online help to PDF format. But now, at this moment, near the end of the project, you face the problem of content organization. You have so much content, it seems all one giant jumble of information. It needs to be organized better, with a sounder logic and structure, but how?

Attempting organization

In setting up my 200 help topics, I initially grouped the topics into various folders — for example, Covert Operations, Stings, Exchanges, Drop-offs. And then I titled the subfolders in each folder as “Basic Tasks” and “Advanced Tasks” to follow the model of increasing agent permissions. So the folder organization looked like this:

Covert Operations
     Basic Tasks
     Advanced Tasks

Stings
     Basic Tasks
     Advanced Tasks

Exchanges
     Basic Tasks
     Advanced Tasks

Drop-offs
     Basic Tasks
     Advanced Tasks

It soon was clear that no one understood what constituted a basic and advanced task, so I changed these subfolders to a grouping of content by role: “Super Agent Tasks” and “Regular Agent Tasks.” I structured everything in the help this way, assuming that this model would fit the majority of agents perusing the help. They could then navigate to the subfolders based on their known and probable role.

Covert Operations
     Regular Agent Tasks
     Super Agent Tasks

Stings
     Regular Agent Tasks
     Super Agent Tasks

Exchanges
     Regular Agent Tasks
     Super Agent Tasks

Drop-offs
     Regular Agent Tasks
     Super Agent Tasks

Feedback from both colleagues and users resisted these roles. “The folders are too general,” one colleague said. “I have no idea what Regular Agent and Super Agent Tasks mean. You need something more descriptive.” A user echoed the same thing, asserting that the folders were too general and vague.

Technical distractions

Release dates drew near. Although the folder naming conventions weren’t ideal, I was proud of the single sourcing model I had set up. The online help single sourced to a PDF printout without any modification of the PDF at all. In fact, I even set up a recurring job to automatically republish both the online help and PDF every day at 2 p.m. It was a completely hands-off, automated process.

But then something happened. A few days ago, one of the chief agents in the department mentioned he was preparing a presentation to a set of field agents, and could I show him where to print the quick reference guides and user manuals?

Gladly I showed him the links, but because I had a few days until the deadline, I decided first to read through the PDF, which previously I had hardly glanced at except to ensure proper formatting and PDF rendering.

Printing out the PDF, which essentially duplicated the online help but in print format, was 197 pages. I didn’t realize it was so long, but I pulled out my red pen and started to proceed through the topics with patience and anticipation.

Non-linearity and linearity

As I moved from topic to topic, I noticed that the topics didn’t flow well together. Some topics repeated information stated on other topics. Other topics introduced concepts in some places but didn’t include tasks related to those concepts until pages later, as they were interrupted by other topics.

Overall the content was too detailed, too wordy, and too long. I drew big red slashes on numerous pages and wrote “Cut” more times than I could count. I wanted a shorter reading experience. After page 50, I had read all I wanted to.

The chief agent’s assistant also agreed that she could not print 197 pages for each participant. The length seemed ridiculous. Was the application really that complicated?

Somewhere, something had gone wrong. I entered into the project with a couple of assumptions. First, I assumed help should be a mile wide and thirty seconds deep, that is, covering a wide array of topics in a brief way. Consequently, I had written dozens and dozens of topics that covered all kinds of scenarios. This might have been all right had I left the miles of topics in the online help, but I had also included these topics in the PDF.

Reading through the PDF, there was no flow, no tight coherence of ideas, no transitions from one idea and topic to the next. It was if someone gathered 200 Post-it notes written independently of each other and positioned them sequentially — and then was surprised when the content lacked flow from one Post-it note to the next.

I had another faulty assumption, one that I knew but had forgotten. Online help is a non-linear reading experience. A printed document is a linear reading experience. The two reading modes aren’t interchangeable. Reading through the PDF made that clear.

Crumbling organization

I noticed another problem in reading the PDF. The chapter titles Super Agent Tasks and Agent Tasks began to annoy me, even more now than before. What did they really mean? Nothing. As my colleague had pointed out, the titles only meant something if you knew what sort of tasks each role could perform (which I did).

But if you didn’t already know the limits of each role, grouping topics by role wasn’t helpful. You would only know to look in that role’s folder if you knew that role could perform that task. But most users wouldn’t know the tasks each role could perform. Many of them wouldn’t even know what roles the application had. So the folder names were somewhat meaningless.

The help file was falling apart on two levels now: poor folder/chapter titles, which left the organization of tasks vague. And also a hodgepodge of clashing topics in the PDF output, which didn’t result in a linear reading experience.

Blog Sponsors

Does Design Matter in Comparison to Content?

Tom Johnson — Sun, 16 Nov 2008 08:22:34 +0000

Last week I made some alterations to my site’s design, but no one seemed to notice. In fact, few people have ever commented about my blog’s design at all. The same goes with the music intros for my podcasts. I can change the music each time, and no one ever responds.

In contrast, if a post has good content, I see a steady stream of comments. My experience leads me to conclude that content is about 90% important, and design is 10% important.

My colleague Ben Minson wrote a post explaining explaining a similar point. He said,

… Designers place more importance on good design than do users, while users do the opposite. I have to side with the users on this one. Outdated information alienates and frustrates users, and no amount of “good design” can make up for that. Would you say to yourself: “I want to kick my computer because the information on this site is so wrong!… But the site looks nice, so it’s not a problem.” If you believe good design is better than up-to-date information, maybe you’d better stick with a cool, soothing color scheme. (“Results of a Study about Online Experience“)

Heavy visual design (left) versus minimalistic design (right). Which do readers prefer?

Despite the irrelevance of a nice-looking site, I still find myself, on the weekends, tinkering with WordPress design. Last week I did all of the following to my theme:

Changed from two sidebars to one because it looked cleaner and simpler
Widened the sidebar column to accommodate more content
Changed the background color of the sidebar to gray
Customized the Podcast page’s sidebar with sidebar content specific to podcasts
Reduced the number of subscription icons on the home page (moving the Podcast-Only subscribe buttons to the Podcast page’s sidebar)
Moved the location of the subscription buttons to the banner area rather than the sidebar
Added an About section at the top of my sidebar
Added an Advertising button on my toolbar
Implemented WordPress’ caption feature for images (by far the coolest thing I did)
Increased the kerning on the word “Writing” in my banner logo
Changed my tagline from “technical communication blog” to “a blog about the latest trends in technical communication”

Did you notice any of these changes? Probably not many. In general, do readers care about design? Not unless it gets in the way. Mostly users come to your site for the content. Similarly, in help authoring, your users come to the help to read the help, not to admire the design. Good design promotes the content well, gets out of the way, and is somewhat invisible. (I wrote about this here.) In this sense, good design is less design.

That said, your site’s visual design does, however, have some influence on readers. Design contributes to the split-second judgment that readers make about the authority of the site. If your site looks professional, your content may seem more authoritative.

However, a professional site doesn’t have to be ornate, or full of color and eye-popping graphics. A professional looking site can be minimalistic, white, and fairly plain. I’ve noticed that I tolerate minimalistic themes on my blog much more than others. They’re less likely to be an eyesore; they don’t distract from your content.

For example, look at the themes of these popular blogs:

Design is minimal with each. And of course don’t forget the quintessential example of successful minimalism: Google. Google’s site is almost 75% white space, but few complain because that’s not why they use the site.

I'd Rather Be Writing » content

Messages from Sponsors — January 2012

News from Madcap

News from Dr. Explain

News from Scriptorium

News from Tedopres

News from Adobe

Blog Sponsors

Looking at Breadcrumbs in a New Way

Blog Sponsors

On Content Strategy and Identity

Blog Sponsors

WordPress Workshop Outline for the STC Summit

WordPress Workshop Outline

Blog Sponsors

When Help Content Is Forgotten

Two Types of Content

Different Content, Same Question

Brainstorming Ideas

Conclusion

Blog Sponsors

Podcast: Finding and Creating Relevant Content — Strategies for Social Media

Blog Sponsors

Students Contemplate Whether a Technical Writing Career Will Be Fulfilling

Blog Sponsors

From Help Authoring Tools to Web Tools, Especially Wikis [Organizing Content 12]

An Electricity Fast

Time to Take the HAT Off

On to Wikis

Which Wiki?

A Maze of Chaos

Wiki Categories

Still the Same Challenges

Categories and Subcategories

At the Highest Level, Categories Fail

Blog Sponsors

Things Fall Apart, The Centre Cannot Hold [Organizing Content 3]

Technical distractions

Non-linearity and linearity

Crumbling organization

More content, but no space for it

Blog Sponsors

Does Design Matter in Comparison to Content?