Sponsors

• Open Help Conference
• Docutools
• 3Rabbitz book
• Southern Polytechnic: Information Design and Communication
• Simplified English
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite 4
• Plagtracker: Plagiarism Checking Service

In this scenario, you have a lot of different information, much of it overlapping. For example, with your ACME widgets, you have some conceptual info, some strategic info, some configuration info, some management info, some API info, and some server info — all related to the ACME widgets.

The sales people need the conceptual and strategic info but don’t want to be burdened by the configuration, management, API, or server info.

The developers mostly need the API info and server info, though they do need some light familiarity with the conceptual info as well. They don’t need the strategic info since the developers implement the spec from another team that formulates the strategy.

The administrators need the configuration and management info but not a whole lot of other info.

If you were working in a help authoring tool (HAT) or another model, you could create all your content as standalone topics and then produce three distinct outputs — one for each audience. Your developer guide could include the API and server info while providing light conceptual topics as well. Your sales guide could walk through the conceptual and strategic components while omitting the more technical content of the other guides, and so on.

The model of distinct outputs for distinct audiences is a model many technical writers are familiar with. It works because the information sets are walled off from each other in clearly separable ways — the help for the developer opens in its own web view and navigation. Search results are restricted to that web help file only.

But rather than publishing independent, standalone outputs, in this scenario you’re using a web platform for all your help content. It would be odd to have multiple instances of the web platform. For example, you wouldn’t have one Drupal instance for developers, one Drupal instance for salespeople, and one Drupal instance for administrators. You could technically do it, of course, but managing all those separate web platforms would be a headache. Instead, you have one web platform for all your content.

How do you re-use content intelligently on the same web CMS platform?

Approach 1: Push the same topic out to different TOCs.

You could store the topics in a re-usable format outside the web platform and then push out the topics multiple times, sometimes including the topic in the information’s table of contents (TOC) and sometimes not.

However, having multiple versions of the same topic appear in different places on the same site gets confusing. Your search results would show redundant instances of the same topic, and the overall content on your site would perhaps double or triple in size. The user browsing around the various pages would see a lot more content, much of it the same but repeated. So this approach seems odd and inefficient.

Approach 2: Pull the same topic into different TOCs.

You could write each topic as its own article and then pull the same topic into different content TOCs. For example, if you have a “Configuring Widgets” topic relevant to both administrators and developers, you could create one article about Configuring Widgets and put the same topic in both TOCs — in both the TOC for developers and the TOC for administrators.

The question is what TOC shows when you view the topic? You can’t have multiple TOCs appear, so viewing the topic would potentially decontextualize the user from the TOC he or she was previously navigating.

Approach 3: Create tag-based views of topics.

You could create each topic as its own article but tag the content with keywords such as configuration, sales, API, management, and so on. Users could navigate by tag and see all the topic results that have that tag. Clicking on the “ACME widget development” tag might include the server, API, and configuration topics. Even more granular tags inside of these tag buckets could allow users to further filter the information they see.

Although the same topic might include multiple tags and so appear in multiple views, this filtering of content is more familiar to readers as they would probably know that one topic can have more than one tag.

The problem with a tag-based navigation is that you lose the hierarchy of a TOC. All files become a flat, unordered list of topics. The lack of hierarchy makes it more difficult to understand the meaning and structure of the information at a glance.

Approach 4: Abandon the TOC, provide search only.

In this approach, you pretty much abandon the TOC and instead provide a search field only. Vimeo’s help looks like this. The search provides instant results that take you to a specific topic, but the topics aren’t organized into different navigation TOCs and such. The book paradigm seems far left behind here.

The problem is that users can find only what they know to find. The search helps answer a question but not teach users what’s possible. There isn’t a logical path through the content to help users learn a new system. Instead, there are lots of disconnected, floating answers. There’s no clear progression to follow through the content, so it gets tiring.

Conclusion

Which approach do you use? I’m not sure, but here’s my point: On the web, the traditional paradigm of navigation via a table of contents breaks down. So do traditional tech comm patterns for content re-use. We have to consider new paradigms for how we organize content when we put all content on the same web platform. Companies that try to impose the book paradigm into the web end up with a content mess.

What do you think? What approach would you use?

Sponsors

• Open Help Conference
• Docutools
• 3Rabbitz book
• Southern Polytechnic: Information Design and Communication
• Simplified English
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite 4
• Plagtracker: Plagiarism Checking Service

5/22 note: The previous title was “Structured Authoring Versus the Web”. However, of course the web uses structured authoring. Every web form in this post — the title, body, category, tag, date, featured post — are all forms that take their input and semantically identify the content. My original contention was the highly structured DITA format that is geared for content re-use and conditionalization. Hence the title change.

I recently listened to the Scriptorium webinar on the State of Tech Comm, which I found well-worth my time. One theme I keep hearing is a trend toward structured authoring. In Scott Abel‘s benchmarking survey (which the webinar uses as a starting point), Scott found that 44% of companies are using structured XML content, with 81% of those companies using DITA for their structure.

Clearly structured authoring is a trend with a lot of momentum. At the same time, structured authoring doesn’t seem to include a website format. Mark Baker noted this absence of a website output in a discussion the other week. He said,

The thing is, at the moment, there are no structured authoring systems for the Web. DocBook was designed for book. DITA was developed for help systems. Both output to the Web, but they don’t produce Web-like output. In fact, their output looks pretty much the same as the output from FrameMaker.

We have lots of unstructured platforms for the Web, but no structured platform. This is why I am developing SPFE — to be a structured writing architecture for the Web, and for EPPO.

Although structured authoring is no doubt a major trend in help, an even larger trend is the move toward the web. Given my love of the web and web-based platforms for authoring, I’m a little mixed about structured authoring methods like DITA. I wish structured authoring were more compatible with a web paradigm. In fact, I think the next evolution of structured authoring will involve a stronger integration with web platforms.

In this post, I’ll pit structured authoring against the web and let the two go boxing for a while.

5/22 update: Note that when I say “web”, I’m not referring to the tripane help or CHM help or HTML help that is formatted with HTML and published onto a website. I’m referring to an actual website, like the one you’re reading now, or something like A List Apart or some other content heavy online site with comments, online content management, usually a database backend, tags, custom design, and more web-like features. Almost all tripane help (like this one) is contained in its own little frame that combines the content inseparably from its output format.

What is structured authoring?

First, a brief definition of structured authoring. Structured authoring involves applying a consistent pattern to your content, such as always following a specific sequence of tags.

Most structured authoring models use XML to define these tags. The tags are semantic in nature and don’t include any formatting themselves. Instead, you use a transform language (XSLT) to apply formatting rules based on those tags. DITA, S1000D, and Docbook are all examples of structured authoring.

For a great explanation of structured authoring, see this white paper on Structured Authoring and XML from Scriptorium.

5/22 update: There are lots of varieties of structured authoring. In this post I’m referring mostly to DITA, not to all semantic tagging of content, HTML5, or some other markup. In tech comm communities, structured authoring usually refers to formatting content in a specific markup that is validated against a DTD before rendering it into an output. Of course there’s lots of structure on the web and the web wouldn’t be useful without structure. But does it make sense to use the DITA structure in publishing to a website? That’s my real question here.

Why use structured authoring?

Structured authoring gives you several advantages:

Separation of content from format

By removing formatting tags from your content, you liberate your content to go into more places. You can output to an infinite variety of formats based on whatever transformation engines you can apply to your semantic tags.

In Meaning and Metadata, David Farbey relays Karen McGrane’s advice in writing for mobile:

Don’t encode meaning in visual styling

In other words, don’t use a WYSIWYG editor to apply inline styling to your content. Most people agree that if you want to repurpose your content in more than one way, you need to separate the content from the visual display. Structured XML provides this separation of content from format.

Content re-use

Let’s say you write Topic A and want to re-use the same topic in another output. You can create various maps (or tables of contents) that have different combinations of the content. You might create a map that includes only beginner topics, or one that’s more comprehensive for administrators.

Your product might have various versions, with some topics applying to some versions but not others. By writing in small topics that can be combined in myriad ways, you have more flexibility for output combinations.

The reason these small topics are interchangeable is because they all have the same syntactically tagged structure and can be parsed predictably by the XSLT language.

Translation

If you need to translate your content, you’ll need to have it in an XML format that a translation memory system can handle. XML formats make this export-and-import workflow a sane process to manage.

Universal format

If you acquire another company, you can easily integrate their documentation into your own, with your own branding and formatting, as long as their content (and your content) both use an XML format. When writers store content in XML, it can be exchanged and re-used more easily.

DITA was created by IBM in part to solve the problem of mergers and acquisitions that a large company like IBM regularly engages in.

Predictability

Structured content follows a predictable format that makes authoring easier. When readers can predict the format, it aids comprehension more quickly. It also reduces the number of decisions technical writers must make as they author content. The recipe model is often cited as an example here.

And in the other corner …. the web!

Clearly structured authoring has a lot of advantages with content. However, structured content has a hard time finding its way onto the web. Here are a few advantages of adopting a web platform for your help.

Transforming the structured XML content is a burden

Separating content from format has both advantages and disadvantages. Although you free the content to be output to any format, you also suddenly have a challenge now to define the XSLT rules behind that content transformation.

The PDF output from DITA is notoriously plain, and the web help HTML output is not usable by itself. You either need to hire a programmer to create your output for you, or you need to pass the output into another tool, like Flare, to transform your online output.

With many tech writing teams constrained with small budgets and few resources, hiring a dedicated publishing engineer to handle the transforms, or contracting out the work at a high cost, really isn’t a practical solution.

Many web platforms already have a lot of attractive themes that writers can quickly leverage for a professional looking output. It’s tempting to just adopt one of these web-based themes for help instead of defining one from scratch.

Websites provide better mobile display

One might think structured content leads to a better mobile workflow, since you can output content with a specific mobile view. The problem is that this model supposes that you should have a separate mobile output at all.

In contrast, responsive web design allows you to apply different stylesheets to the same content. The CSS3 style tags can be defined based on the viewport size of the user’s browser. Just add div tags with unique IDs to your heart’s content, and then you can style that content in different ways.

For example, this website has a mobile element to it. View it on your mobile device (or shrink the browser to a mobile-like size) and voila, the content responds to your device and still looks readable. You don’t need to go to a separate site that has a separate output with a mobile transformation. There’s just one source.

While you can generate a mobile output from structured content, you often end up with two different sites — one for mobile viewers and one for regular viewers. The problem is that you can’t determine what sort of device a person will use to arrive at your site — smartphone, tablet, or computer. Therefore you can’t always route people toward different sites, and even if you could, users often don’t want a different version of the content. They want the full content.

It’s possible to use structured content to generate a single responsive output for both desktop and mobile, but then what’s the point of the multichannel output that structured authoring yields?

PDF formats mislead users

When people talk about the benefits of structured authoring, they often talk about the various outputs, saying you can output to desktop, mobile, PDF, Kindle, ePUB, and more.

But if you break down these options, very few help manuals need to be published to Kindle and ePUB. In most cases, a mobile view and a desktop would probably be just fine. What about PDF?

I don’t offer a PDF output because I don’t want users printing off help content. The last time I created long manuals, users would show them to me and not realize they were outdated. Users don’t often know that help changes quickly.

In agile environments, help material potentially changes every two weeks. By giving users a PDF to print, you set up a situation for user frustration. As users follow the outdated manual and realize the steps are “inaccurate”, they’ll complain and your help will lose credibility. Better to maintain one source that is always up-to-date and online.

I think the PDF form is dying precisely because it doesn’t keep pace with agile environments. Information changes too rapidly to hold any kind of lasting permanence through print. As an example, go to your local library and peruse the computer books section. Most of the books are new but at the same time outdated. You get the sense that the information is no longer the most current.

In cases where you really need to provide a PDF, you might be better off creating a quick reference guide that is an abbreviated (for example, 2-5 page) version of the help content, written in an introductory, condensed way. You could try single sourcing that quick reference guide, but it’s usually more trouble than it’s worth (compressing 200 pages into 2 pages requires a different style of writing — one that is much more compressed).

Additionally, you can add a print stylesheet to your web pages. The print stylesheet usually strips off the navigation and any other web frames to provide the content only. You can also usually pull multiple pages into one printable view. For users who want to print content, this web printing capability might be just fine.

Content re-use is overrated

If all your help material is available on a single website, you have less of a need for content re-use. On a single web platform, there are different navigation options (tables of contents) based on different needs. And if one section needs the same information from another section, you simply link to the other section.

You don’t generate a beginning and advanced guide on the same web platform, repeating topics across the site — doing so would add a lot of confusion with search results, in addition to unnecessarily bulking up the documentation. For more on content re-use on a website, see What Does Content Re-Use Look Like in a Web CMS?

The one-platform-for-all-content model has some unique advantages. If users want to search for a term, the search looks at all content. You avoid the siloed situations that often result in No Results Found scenarios.

Additionally, all your content automatically inherits any change you make to your platform, so you don’t have to regenerate 20 outputs when you make an update (to something like your copyright notice).

For more discussion on this topic, see Two Competing Help Models: One Stop Shopping or Specialized Stores.

Versions are going away with the cloud

If I had to support different versions of the same software, I could see more of a business case for content re-use. However, in the software as a service model (SaaS), your platform is generally in the cloud, so users generally don’t have different versions of the software. You don’t have to push updates and hope people upgrade (like Internet Explorer 8, 9, 10). We don’t really live in that kind of world anymore.

Now software companies update their platform on a regular basis, and all companies who are subscribed to that service get the update automatically (because they didn’t download anything from the start). As such, the whole idea of versions is diminishing.

In the most radical example, Adobe recently announced that they are moving toward a cloud solution with the Creative Suite. Imagine the cheers from the tech comm department when this announcement was made. This means tech writers won’t have to support different versions of the Creative Suite going forward. There’s just one version — it lives in the cloud.

5/22 update: Okay, I overstated this a bit. Drupal, Atlassian JIRA, and other platforms do often have multiple versions simultaneously. This is because the latest version often changes dramatically from the previous version, which requires customers to revamp their hooks or other integration details. As a result, the companies can’t force all customers to upgrade to the latest version. 

Predictability versus natural flow

Some authors like how structured content enforces a specific form and pattern to help content. In a recent exchange on my blog, I compared this model to a straightjacket, while Mark Baker responded that it’s more like a tailored dinner jacket.

In a paradigm of “content first,” it seems like we should be writing in forms that fit the content. How many people have protested the designer’s use of lipsum dolor because it presents dummy content wrapped in a prepackaged structure, which may or may not fit the content?

But in the end, how is this dummy content on a web page mockup different from a help format that prescribes a similar pattern of sections?

At any rate, a simple style guide can help create consistency. You don’t have to enforce that consistency with an Document Type Definition (DTD) that prevents anyone from publishing unless they conform to the definition. Let’s lighten up, people.

I like to find a natural shape for content rather than restricting myself from the start with a general shape that doesn’t always work.

Collaboration requires an easy update process

One thing I have learned recently is that my presence in any company is ultimately temporary. Whether I’m there 2 years or 5 years, one day I’ll be gone. And usually I transition from department to department, project to project with a lot more frequency. What happens if I write content in a structured format? Will the product managers and other subject matter experts (SMEs) be able to pick up where I left off to continue authoring?

As far as I can tell, all the help in my Flare files at my previous job remain untouched. I check the help sites every now and then to see if perhaps someone has cracked the code and figured out how to update the help. They haven’t. How I wish I’d simply kept the Mediawiki format as before, since it enabled so much better collaboration.

With so much information to know, it’s more important to collaborate with other SMEs. I want a format where all users can contribute and take some ownership. The idea of having a process or tool so specialized that only a technical writer with a special skill set can contribute leads to the same single-author paradigm that creates myopic help. I once wrote about this syndrome in Why Help Authoring Tools Will Fade.

In contrast, with a web-based platform, you enable collaboration. You distribute and share content ownership. This point alone about collaboration is worth adopting a web model for authoring and publishing.

Offline authoring is so passé

Perhaps my final qualm with structured authoring is that it seems so offline. The direction of the web seems to be moving toward a more sophisticated in-the-browser experience, where you read and write directly in the browser.

Granted, authoring in a browser’s rich text editor kind of sucks, but If I had to compile my blog posts and render them out to an output and then upload the content to a web host every time I wanted to make an update, I wouldn’t make too many updates. You shouldn’t have to author outside the browser to publish on the web.

Web allows you to harness web technologies

There are many web technologies that empower us to go beyond the old model to achieve so much more. If we’re on the web, we can take advantage of these technologies in a much easier way.

For example, let’s say you want to take advantage of faceted browsing with search filters that dynamically appear on your search page. Or you want comments below posts. Or an RSS feed so users can subscribe to updates. Or revision histories, or some interactive JavaScript demo, or collapsible sections, or a Twitter stream, or different views of the same content based on tags, categories, dates, etc, or gamification and its points and badges for users as they advanced through levels, or Youtube videos that cycle through a thumbnail gallery. It would be easy to implement all of this on a popular web-based platform.

5/22 update: See Moving Beyond the TOC in Organizing Help Content for more info on the need for faceted browsing.

In contrast, a structured authoring model makes it much more challenging. Trying to continually port your structured content into a web-based platform for publishing seems kind of cumbersome. You can do it, probably, but not without some custom scripts. And then you run into other issues, such as how you overwrite an existing pages without removing its revision history, comments, location, tags, and so on.

The web wasn’t built with a model that involves continually deleting and republishing the same pages. Instead, many web platforms are built on a database model of dynamically pulling out the content you want and rendering it in a view. This is still a separation of content from format.

For example, I changed out my entire theme last week (from Canvas to Twentytwelve), and was able to do so in a few hours because the content is stored in a database while the theme files live in a separate file directory. And I didn’t need to hire a team of programmers to do it. The web simply makes it easy to publish and distribute information.

It amazes me to think that with all the web advancements, the 25,000 plugins created for WordPress alone, there has yet to be someone who has created a DITA microformat plugin for WordPress, or for Joomla, Drupal, any other web-based CMS (by DITA plugin, I mean a plugin that alters the authoring form, not an import plugin).

Is structured authoring so far from the concerns of any web designer and developer that no one has bothered to code such a plugin? Why don’t designers and developers seem to care much about structured content? Invariably structured content seems a concern of the technical writer only. Why is that?

Conclusion

I don’t want to come across as being against structured authoring. As I mentioned in the introduction, clearly structured authoring is a trend many companies are following. However, structured authoring has a few challenges before it can live in a web environment. In this post, I mentioned a few trends that I think pose challenges to structured authoring:

• SaaS decreases the requirement to support versioned content.
• Agile makes print publications potentially out of date every two weeks.
• Collaboration requires a form that SMEs can edit, update, and potentially author themselves.
• Mobile works best on a website with responsive design.
• Budget cutbacks force small teams to figure out their own publishing solutions.
• Open source platforms provide a lot of capabilities that we can easily leverage.
• Browser-based editing simplifies the update process, which helps us keep up with rapidly changing information.

I would readily welcome a marriage between structured authoring and the web, and I’m glad to see pioneers like Mark Baker attempt to harmonize the two with his SPFE architecture. Already some DITA vendors are starting to integrate DITA authoring in web environments. See this promising Alfresco integration from Componize.

If DITA and other structured authoring forms want to keep pace with the web, they’ll probably follow a similar pattern as Componize. Hopefully at some point, the web CMS will eventually stand alone, with DITA perhaps running the engine but not showing itself to the user. But until then, one almost has to choose sides: structured authoring, or the web?

——————-

May 17 Update: For some other perspectives, see Sarah O’Keefe’s Structured Authoring AND the Web, Mark Baker’s Structured Writing FOR the Web, and this summary from Techwhirl: Can Structured Authoring and Web Content Delivery Co-exist?

Sponsors

• Open Help Conference
• Docutools
• 3Rabbitz book
• Southern Polytechnic: Information Design and Communication
• Simplified English
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite 4
• Plagtracker: Plagiarism Checking Service

In my previous post, Do Short Topics Make Information More Findable, I argued that shorter topics make it more difficult for users to find information. I ended the post by saying that topics that are more substantial make content more findable.

But how big should the topics be? Obviously not the length of a book, because that switches us right back into the book paradigm.

There’s probably not an exact way to determine topic length, because so much depends on the context of the information and the task at hand. But basically, a good topic answers a good question.

What’s a good question? Questions can scale to a low or high order, being very specific and mundane to being abstract and conceptual. A one-sentence topic might provide the answer to a question (e.g., How many feet are in a yard?), while a 300-page dissertation might provide the answer to another question (e.g., What was Chaucer’s influence on the Renaissance?).

In other words, you could construct the question so that it scales for any length of topic.

However, if you can construct an intriguing question (or at least a relevant question within the user’s business scenario), that question merits enough information for a good-sized topic.

The following table lists some good questions versus lower-order questions in what might be a help file for an SDK.

The lower-order questions all lead to a quick one paragraph response. On the other hand, the “good” questions will require more detail.

Granted, not every system merits longer topics. For example, if you have an encyclopedia of birds, each entry is probably a bird description in your TOC. But for most help topics I’ve written, I think a good sized topic is usually around 500 to 1,500 words, with exceptions.

Why 1,500? In an earlier post I wrote, Making Help Content Enjoyable to Read — Impossible Question?, I noted that Clive Thompson of Wired magazine says the most popular blog articles are about 1,600 words in length (see “Clive Thompson on How Tweets and Texts Nurture In-Depth Analysis”). 1,600 words is about a seven-page double-spaced essay. Granted, that’s probably not a help article, but it bucks the idea that each web page should be short little snippets of thought.

Length alone isn’t much of an argument. So why do longer topics make content more findable? Here are several reasons.

Reason 1: Fewer Search Results to Sort Through

First, the obvious argument. If a user searches the help, there are fewer results to sort through if the topics are lengthier. For example, if you don’t present the user with 37 hits for “widgets”, it’s more likely that the user will open (perhaps among 5 choices) the right search result containing the answer.

Reason 2: Browsing Becomes More Practical

If users don’t find anything via search, they can browse the table of contents (TOC). Longer topics mean fewer TOC entries to browse through. The TOC that was once impossible to parse through is now something that users can glance at and get some meaning from.

Reason 3: Interconnected Learning Helps Users Learn More

Now for the insightful, compelling reason why long topics are better. Information that is grouped together increases the inter-relatedness of information, helping users see the larger picture about a topic they’re interested in.

For example, If you have 10 separate topics about widgets, the user may land on “adding widgets” and find a quick answer but not realize that he or she can also “fork widgets” or perhaps “decompile widgets.”

By grouping related information about widgets together, you increase the chances that users will broaden their understanding of a concept and leave with more knowledge than they arrived.

In short, browsing through a long page of content helps users discover what they don’t know.

Almost every grocery store uses the tactic of the long page. You arrive at a grocery store for milk, eggs, and bread. Almost always, the grocery store puts those items in the back of the store, forcing you to visually “sort through” all the other goods in the store. By the time you make it to the mlik section and then to the checkout counter, you’ve picked up a box of cookies, some lunchmeat, and some macaroni that was on sale.

Long topics create the add-on learning for your users. The user who just had a quick answer about hummingbird wingbeat speed suddenly learns that some hummingbirds weigh less than a penny, can live up to a decade, and are the only bird that can fly backwards. If all of that information had been separated out into discrete topics, the user would have probably walked away with the wingbeat speed answer only.

Try this experiment yourself. Click the following two images and check out the difference in content. The topic on the left, from Askville.com, is a short paragraph only, while the Wikipedia article on the right is quite a bit longer.

While the Askville page gives you a specific answer, the Wikipedia page gives you information that you didn’t even know to ask. Which approach to you prefer?

In summary, even if long topics don’t deliver information faster to the user, they’re a better practice because they help the user learn more through a tighter grouping of information.

Long Topics Are More Maintainable

I have a few other points to make about advantages with long topics — they are much more maintainable. If you have thousands of discrete topics in your system, not tightly connected together, maintaining the information as a coherent whole when you need to make updates becomes a nightmare.

For example, let’s say you have 20 topics about hummingbirds. Your subject matter experts push out new findings that change some aspects of our hummingbird knowledge. Now you have to hunt and peck around your help system for all the various topics that touch on hummingbirds. If the information were grouped together, you can more easily see the places you have to update.

Ways to Break Up Long Topics

So that my advice isn’t misconstrued, I’m not suggesting that every technical writer suddenly start creating long walls of text.

A page of long text needs to be broken up by subheadings, graphics, lists, and white space. A great reference for designing the visual aspects of a page (not necessarily adding graphics, but influencing the visual nonetheless) is Visual Composing: Document Design for Print and Digital Media.

When a Topic Is Too Long

Although I like longer topics, there’s a practical limit to a topic’s length. When I’ve gone over 2,000 words with my blog posts, I’ve noticed that the comment count plummets. The web form doesn’t work well with really long content. That’s why I actually broke this post and its predecessor into two parts.

While blogging and tech comm are separate genres, the predominance of blogs on the web has set a trend for expected article length and attention span online. A good editorial is usually about 800 words for a reason. Just as a Windows PC has trouble moving around information more than 2GB, our brains also have trouble working in 2GB topics. Shorter is cognitively easier to handle. But not too short.

Sponsors

• Open Help Conference
• Docutools
• 3Rabbitz book
• Southern Polytechnic: Information Design and Communication
• Simplified English
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite 4
• Plagtracker: Plagiarism Checking Service

Most users I have written for have no desire to read or skim through a long page of information. They want an answer to a specific problem. For these users, chunking instead to [create] narrowly defined topics is far preferable, even if it results in a longer table of contents. Providing an effective search mechanism is increasingly vital to the usability of any content, and search paired with small topics is an efficient way to get your users the specific answers they need.

In other words, shorter topics make it easier for users to find the information they’re looking for, since there isn’t as much content on the page to sort through.

I don’t single this comment out for its uniqueness but rather for the way it touches upon minimalism and a general style with topic-based authoring.

Is it really true that shorter topics increase the findability of content?

When The Short Model Succeeds

In some cases, I agree that a short topic might make information more findable. For example, when a user formulates a precise search query that connects dead center with the right topic, a short topic that answers the question more concisely than a long page helps the reader get to the information more quickly. Online examples of successful short topics might be Yahoo Answers or Stack Overflow.

Unfortunately, except for simple, direct questions, that kind of search-and-retrieve accuracy with help content doesn’t always happen. More frequently, the search fails to connect to an answer in the help, which forces the user to instead browse around for the information.

If the information is fragmented into too many small topics, the browsing becomes frustrating for the user because the table of contents has too many paths and sub-paths and sub-sub paths. This leads the user to attempt more searches, which often turn up fruitless. After pogo-ing around on half a dozen short topics without finding the answer, the user gives up.

Let me expand more on the three main reasons why shorter topics don’t always increase the findability of content.

Reason 1: The User Doesn’t Know the Right Terms to Search For

The search-and-retrieve argument for short topics assumes that the user knows the right terms to search for. Yet routinely, interfaces and applications use a terminology foreign to the user. The application might use “widget” instead of “sidebar section,” “module” instead of “plugin,” “template” instead of “php include,” and so on. Without a knowledge of the correct terms, the user won’t be able to connect to the right topic via search.

Reason 2: The User Doesn’t Construct Well-Formed Search Queries

The second reason the search-and-retrieve model fails is because users don’t often construct well-formed search queries. If you’ve ever looked at a list of search queries from a web analytics engine, the queries are short (one or two words), vague, and often hard to understand.

For example, a user searching for information on setting up a widget might simply type “web layout” or “design site.” The chances that this search connects with the topic “Configuring and Setting Up Widgets” are small.

According to Jakob Nielsen, users get progressively worse with each query reformulation:

Given that search is becoming old hat on the Internet, you might think users would develop advanced search skills. Not so.

Typical users are very poor at query reformulation: If they don’t get good results on the first try, later search attempts rarely succeed. In fact, they often give up. We recently studied a large group of people as they shopped on various e-commerce sites . Their search success rate was:

- First query success rate: 51%

- Second query success rate: 32%

- Third query success rate: 18%

In other words, if users don’t find the result with their first query, they are progressively less and less likely to succeed with additional searches. Many users don’t even bother: In our study, almost half the users whose first search failed gave up immediately. (See Search: Visible and Simple.)

Reason 3: The User Can’t Articulate the Real Problem

The third reason the search-and-retrieve model fails is because users often cannot articulate the real problem they’re having. Users can’t search for concepts they don’t yet know. But even if they do know the concept or task they want, it’s sometimes hard for users to articulate what’s actually wrong.

For example, suppose the user is having computer issues with slow performance, viruses/adware, and lack of storage space. The user needs help and wonders how to fix the issues.

In such a scenario, the user might search for a variety of issues but never quite pinpoint the exact issue. The user might search with queries such as “computer slow reboot not helpful” or “remove viruses reinstall” or “disc drive time performance”.

These searches reinforce the idea that the user doesn’t exactly know what he or she needs. That’s why the user is searching in the first place — to try to find information. If the user already knew the exact terms and question to ask, he or she probably wouldn’t be using search.

(By the way, earlier I wrote about some of these search issues in Browse versus Search: Stumbling into the Unknown Unknown, so check out that post to dive deeper into this topic.)

Reason 4: Users Don’t Rely on Search as Much as We Sometimes Think

There’s another reason short topics fail. We often assume that because we like to use Google so much, users must also use our site’s search box as their default mode for finding anything. Yet  Web Usability Blog found that only about 5% of a site’s visitors used the search (see Navigation versus search).

Even if you account for ten times more searchers, that’s still only half your audience. How are the other half finding content?

If users aren’t relying on search to find the information, they’re most likely browsing. If you’ve fragmented your help into 500 little topics, the browsing experience will be one of constant page hopping.

Solution: Widen the Target

Without a more accurate search, it’s unlikely that users will hit the target they seek. While some technical writers believe the user is a skilled hunter with a compound crossbow aiming at a target 30 feet away, the scenario is more like a kid with a toy bow from Wal-Mart trying to hit a target 100 yards away. The search rarely connects with the right topic. The shorter the topic, the harder it is to hit it.

Shorter topics do add more little targets in the field. So the user has a higher chance of hitting one of the targets, but it’s unlikely that any of the targets will provide the exact answer the user is looking for.

One solution might be to tag short topics with a common tag, and then output related topics as links based on that tag. This provides a second-level navigation experience but relies on the fact that users will scan through related topics and follow links. You’re limited to about half a dozen related links per topic before the list starts to look unhelpful.

Another approach is to make the targets bigger. You make the targets a bit bigger by providing more information in the topic. Rather than fragmenting your help into a lot of little topics, combine and group similar information into a more substantial topic that is likely to address more issues.

How much information should a topic contain, and why is longer better? I’ll make those arguments in another post.

Sponsors

• Open Help Conference
• Docutools
• 3Rabbitz book
• Southern Polytechnic: Information Design and Communication
• Simplified English
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite 4
• Plagtracker: Plagiarism Checking Service

This sounds like a good workflow to me, but I’ve kind of run into a little problem. I want to nest some tasks into larger topics rather than having the tasks stand alone as their own TOC entries. Reason being, if every task has to stand alone in the TOC, I’ll end up with a TOC that looks unnecessarily long and intimidating to users.

For example, let’s say one topic in my help content looks like this:

Configuring Widgets

- About widgets
- Create a widget
- Drag a widget in place
- Change the widget’s settings
- Remove a widget
- Restore deleted widgets

The word count of this topic overall, even with all of these sections and subtasks, is only about 600 words (each of the tasks is light). I could make each subtask here its own TOC entry, but then my help would start to look really long. Imagine if I have 10 topics, each similar to this one. This means my TOC would end up being about 60 entries rather than just 10.

Have you ever visited a website that has 60 navigation options at the first level? Unless it’s a massive news site, you don’t expect to be inundated like this with navigation choices.

What I want to do is merge some child tasks into a parent topic with the HTML web help output.

The Chunking Attribute

I asked a friend how to accomplish this, and he mentioned that there’s a Chunking attribute in DITA that allows you to nest subtopics. Here’s the Oasis explanation of how you nest topics:

The “to-content” token indicates that the selection should be rendered as a new chunk of content.

When specified on a topicref or topicref specialization, this means that the topics selected by this topicref and its children will be rendered as a single chunk of content.

Here’s what the dita map would look like with child1 and child2 nested under parent1.

<map chunk="to-content"> 
   <topicref href="parent1.dita"> 
      <topicref href="child1.dita"/> 
      <topicref href="child2.dita"/> 
   </topicref> 
</map>

It doesn’t seem too difficult. I author the tasks as standalone tasks but then create a more sophisticated ditamap that contains instructions on which child topics to pull into parent topics.

I’m glad DITA allows chunking, though the extra work seems a bit of a hassle. I’ll end up with a lot more files to manage and will have to edit the ditamap more. Still, this method provides some more flexibility.

DITA Best Practices with Chunking?

The method for chunking has led me to consider what DITA’s best practices are for chunking. I’m not a DITA expert by any means, but my guess is that DITA provides a semantic structure for content without being too explicit about how to assemble the content. The DITA specification doesn’t say when you should chunk and when you shouldn’t.

However, I think many DITA users extrapolate that because each task, concept, and reference is a standalone file, then it should also be its own file in the table of contents (maintaining a 1:1 ratio). The result? With each task as its own TOC entry, the TOC looks like a gargantuan list.

I’m not sure how widespread the 1:1 ratio idea is. But here’s a rather lengthy excerpt on principles for writing tasks from DITA Best Practices, by Laura Bellamy, Michelle Carey, and Jenifer Schlotfeldt. There’s no mention about ever chunking/merging subtasks into a larger task.

Separate Task Information from Conceptual or Reference Information

Separate tasks from long conceptual or reference information so that tasks are short, retrievable, and reusable. If you overload a task topic with too much conceptual or reference information, expert users get frustrated because they must wade through information that they might already understand.

Also, ensure that a task isn’t buried in paragraphs of conceptual or reference information. Users won’t expect to find a task buried in a table of reference material. And they’ll probably be upset that they spent so much time digging through information that they didn’t need in order to find that one specific task.

Write One Procedure per Topic

Write only one procedure per task topic so that you can more easily manage, organize, and reuse these topics and so that your users can find specific tasks when they need them. For example, don’t combine the tasks for installing and uninstalling software in a single topic. Users typically won’t need both of these procedures at the same time.

Also, adding more than one task per topic makes those secondary procedures harder to find. When you transform the DITA topics to an output format such as HTML, you’ll see only the title of the first procedure in the table of contents.

Create Subtasks to Organize Long Procedures

Procedures that are more than 10 steps can be difficult to follow, especially if some of the steps are complex or have many substeps. Instead of creating one long procedure in a single topic, break it up into several shorter task topics. You can then assemble those task topics into a logical order that helps users to finish the entire procedure.

To create a set of task topics, start by creating a parent topic, or supertask, that describes the overall task flow. Then, nest the child task topics under the supertask in a logical order. The output will show users what tasks they need to follow and in what order those tasks must be completed.

For example, to describe how to install a database system for a financial services business, you’d need a dozen or more task topics. With DITA, you can organize and link those task topics so that users see a clear sequence of tasks. You wouldn’t want to create a single task topic with 100 steps. Think of your poor users!

The following example divides the task of setting up a nuclear fusion power source for an espresso machine into three separate task topics:

1. Gather permits

2. Identify a nuclear reactor to connect to

3. Prepare your home for nuclear power

To organize these tasks, you can create a supertask topic called “Prepare to install Exprezzoh 9000N” and nest the subtask topics under that topic, as in Figure 2.1. When the DITA files are transformed to HTML, you get the following output.

Figure 2.1. The HTML output of a sequence of task topics.

By dividing long procedures this way, your users aren’t overwhelmed, and they can see the overall sequence of tasks. You can also more easily reuse these shorter task topics elsewhere in your information set if necessary. (See DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA, Video Enhanced Edition, by y: Laura Bellamy; Michelle Carey; Jenifer Schlotfeldt. Chapter 2. Task Topics.)

The authors’ intentions are noble: they want to enable users to go straight to the task without being burdened by so much non-essential information. They might say, Let users who want explanations follow links to concepts. Let’s give the user just what he or she wants: step 1, 2, and 3 as quickly as possible, and so on.

This approach might make perfect sense if each task and concept is somewhat weighty. But what happens when the tasks and concepts are really brief? Then you end up with a fragmented information experience, with information that would normally be grouped together instead scattered all about.

The authors also assume the user has correctly landed on the task he or she wants to perform. But that’s rarely the case. Usually the user wants information about configuring widgets but lands on a topic about creating widgets. Or she lands on deleting widgets when she wants information about dragging widgets.

Is it really better to require the user to jump around in your help system, bouncing from topic to topic like a lost tourist asking for directions from a dozen different people who don’t have the right information? Why not give the user the complete information about a topic on a single topic page?

An Example

Here’s an example of what I’m talking about when I say fragmenting user help into a lot of separate topics can result in a poor user experience.

In my trial of easyDITA, I’m really impressed by the platform and its functionality. It really does seem to make DITA easy. And the interface is attractive and intuitive. But in the help documentation for easyDITA, the way the content is a bit fragmented makes me wonder about using DITA itself. For example, take a look at the DITA Maps topic. Then jump down to the Topic Group and Topic Head topics.

Each of these topics is no more than a paragraph, and one of the topics is just one sentence long. Yep, that’s right. Here’s the full content for Topic Groups:

A Topic Group is simply a Topic Head without a title.

These conceptual topics are in a completely different location from The easyDITA Map Editor book, which contains topics for Adding Topic Groups and Adding Topic Heads.

By splitting each task and concept into its own file and TOC entry, the result is a somewhat scattered organization. You end up with a top-heavy TOC organization. The reader must rely extensively on the TOC to locate information.

I don’t mean to pick on easyDITA. Many DITA-produced help files follow a similar pattern of information fragmentation. Take a look at http://ditainfo.info/ditainfo. As I navigate the topics, I feel as if each page is unnecessarily short. I have to rely heavily on the TOC to navigate my way around. Often I want more substantial information grouped together on the same page.

Although I’m thrilled that a standard markup for help content has gotten so much traction, I can also see why DITA still has so much resistance. When people follow the 1:1 file per TOC entry ratio, DITA-based organization looks nothing like the organization on a typical website.

A typical web page simply has more content on each page. I’m not sure how much more, but few pages have just one paragraph or one sentence. A topic is more like a Wikipedia page, which usually contains several sections.

How Long Should a Topic Be?

The discussion about chunking prompts questions about topic length. How long should a topic be? Here’s a good way to measure length: A good topic often weighs about as much as a blog post. The blog post covers a topic with enough depth to feel meaningful standing on its own.

Of course that analogy makes perfect sense to a blogger, who regularly deals in units of “posts.” But let’s try the analogy from another angle. Let’s consider a fast food scenario that portrays the reader as a consumer.

A consumer/reader stops in at McDonald’s (which happens to organize its food like DITA elements) and asks for some food. How much food should the employee give the consumer?

The McDonald’s employee puts several french fries on the serving tray and hands it to the customer. The customer eats the fries and must get in line to order some more food. The employee puts a couple of buns on the tray. The customer eats the buns and orders more food. The employee puts some cheese on the tray. The customer gobbles the cheese and orders some more. Finally the employee adds the burger on the tray. The customer eats the burger too.

As the customer leaves, he or she feels the experience has been unpleasant. The hamburger would have tasted so much better with all the elements assembled together in one sandwich, the customer notes.

And so it is with help. If you have a hamburger size of information, why split each element into its own topic and force the reader to individually retrieve/consume each piece, eating the cheese separate from the buns, and the buns separate from the burger, and the burger separate from the lettuce?

Information sometimes is much more understandable when presented together in one coherent “meal.” By meal, I’m not talking about the whole grocery store (book) — just enough to fill someone’s appetite.

My Preference

Last week I wrote about collapsing sections and their usability. Despite the shortcomings of collapsing sections, they do present a much more attractive option for organizing content in a way that allows users to go directly to the task or concept they’re looking for, without burdening users with information they don’t want to see. You also end up with a smaller TOC so your help doesn’t appear endlessly long.

I think smaller TOCs better align with navigation patterns on the web. Usually information architects think carefully about the information available on the first, second, and third levels of navigation. You often don’t see information on the second navigation level until you navigate the first level. The third level doesn’t appear until you finish navigating the second. There’s an idea of progressive disclosure at work — you give the reader enough information to guide him or her to down an appropriate path. You don’t put all 600+ options on the first navigation level.

If you’re following a 1:1 file to TOC entry ratio with DITA, though, you wouldn’t have any need for collapsing sections. (If you did use collapsing sections, you’d end up with one collapsed section on the page, which would look confusing and incomplete, like a bulleted list that has just one bullet.)

Overall, I’d really like to use DITA, so I’m probably going to experiment with chunking. But I’m also concerned that such a large number of tech comm people might be following a method that leads them to put one paragraph per topic, and one topic per TOC entry. I don’t know how such a method can result in a successful user experience.

I’m curious to learn how common chunking is among those who use DITA.

Sponsors

• Open Help Conference
• Docutools
• 3Rabbitz book
• Southern Polytechnic: Information Design and Communication
• Simplified English
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite 4
• Plagtracker: Plagiarism Checking Service

You are comfortable creating both code and prose. You have a passion for the web and its ability to solve real world needs and create connections between people. You know that there are many technologies that fuel the web, and you’re like a kid in a candy store when you play with new APIs and discover how they expand your abilities. Your real satisfaction comes when you successfully teach someone else how to use those APIs, though, through a blog post or talking at a meetup. You’ve got a knack for coding: you use patterns and practices such as responsive design, you know your way around jQuery and Modernizr, but you prefer to code in adopted standards. In fact, you occasionally read W3C specifications for inspiration. Maybe you hope to someday edit specs… (See Microsoft Programming Writer I job)

Anne indicated that she is heading in the direction of developer documentation.

I really liked her post. It begins somewhat subtle and then steers right into one of the most challenging questions for a technical writer: How do you become a technical writer who loves code?

As I wrote about in Four Types of Technical Writers Companies Are Looking For, the need for API technical writers is a growing trend, especially in the Silicon Valley area. If you have experience documenting APIs, which usually entails knowing at least one programming language, you have a lot more jobs to choose from.

The problem is that most technical writers love to write words more than write code. We love “language” — but usually we say this referring only to the English language.

In reality, program code is a language, and learning it isn’t too unlike the strain in learning another spoken language, like Arabic or Russian. Symbols, syntax, structure, and keywords all communicate meaning. Why is it that technical writers, especially with a humanities background, might consider themselves lovers of language but fail to see programming code as yet another language worthy of study?

Like Anne, I’m also trying to steer in the direction of developer documentation. Not only does it lead to more career opportunities, it’s also content users need. Interfaces are becoming more intuitive, users more tech savvy. The day when you needed to document how a graphical user interface works is waning. Or I should say, the need can be more easily be filled by a technical writer of average skills.

But APIs require another skill set entirely.  Nothing is immediately intuitive. Understanding how the API works involves knowing how programming works, and specifically the rules of a particular programming language.

With some study and effort, you can learn a programming language, no matter how right-brained you think you might be. See this post on Quora about learning hard subjects. The Quora author explains:

I start from this premise: if there’s a concept that many people have learned in the past, anyone of average intelligence is capable of learning it if they follow certain procedures and if they’re able to remove certain roadblocks.

This means that you have to start by giving up the (surprisingly comforting) idea that “I’m just one of those people who don’t get it.” How often have you heard that? “I’m just one of those people who don’t get technology.” “I’m just one of those people who don’t get Shakespeare.” “I’m just one of those people who don’t get Math.” Etc.

The truth is that you’re one of those people who has tried and failed to get whatever subject you attempted to master. That’s demoralizing, but it doesn’t mean you’re incapable of getting it. It just means that you tried and failed. The benefit of claiming “I’m just one of those people” is that it lets you off the hook. To move forward, you have to refuse to let yourself off the hook.

In other words, don’t give up after an hour of frustration when you don’t immediately understand programming (or in the author’s case, recursion in physics.)

The Quora advice is solid, but in my opinion, the question is not “can you learn it,” it’s how can you love to learn it? That’s the essence of the description Anne posted from the Microsoft writer — someone who playfully experiments with APIs out of curiosity, learning how code works for the love of code. Not some who buckles down hard-scrabble and sees the task through with clenched fists.

I’m not entirely sure how you make the switch from Thomas Pynchon to Python, or from James Joyce to Java, or from Chaucer to C++, but at some point, I think the technical writer who lives and breathes code has to first develop a genuine interest in code. He or she has to see code as a beautiful language, one worthy of study, memorization, play, and delight.

I haven’t reached that point. But I did catch a glimpse of it last week. I bought a personal subscription to Safari Books Online to have more than a dozen JavaScript how-to books at my disposal. At one point, while reading about how web architects tried to solve resource loading issues on web requests, I had an insight that maybe computer language wasn’t just a confusing set of rules some techie made up late at night in his or her garage or basement. Maybe it was much more intelligent, something fascinating, maybe more advanced and complex than human language. Maybe computer language, the way it’s collaboratively constructed, with variables and functions, contains efficiencies and logical constructs that are both revolutionary and profound – even more so than the English language.

That kind of perspective is somewhat fleeting as I read computer books, but I don’t think any technical writer will be successful in developer documentation without first seeing computer language as a language and second seeing its beauty.

Sponsors

• Open Help Conference
• Docutools
• 3Rabbitz book
• Southern Polytechnic: Information Design and Communication
• Simplified English
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite 4
• Plagtracker: Plagiarism Checking Service

Blogging is one way to gamify writing. Blogging introduces game elements to make writing more fun. Blogging makes writing so much fun, in fact, that about 2 million new blog posts are written each day. Let’s explore blogging’s game elements in more detail.

Short Tasks

First, blogging makes the writing tasks short. You can usually write a post from anywhere between 30 minutes and 3 hours. Like a game that has a beginning and end (with sometimes a quick middle), so does blogging.

Immediate Rewards

If you write a good post, you’re immediately rewarded with comments, pingbacks (links from other blogs), and mentions on social networks (like retweets).

If you want to measure the value of the post, you could count up comments, pingbacks, and mentions to arrive at a point score of some kind. But a point score isn’t nearly as powerful as the euphoria of receiving comments, pingbacks, and mentions.

Actually, every time you get a comment, a rush of dopamine in your brain’s neurons gives you a mini-feeling of euphoria (see Techno-Addicts). It’s the same euphoria that drives us to compulsively check our email twenty times a day.

Blogging provides more rewards than merely comments, ping backs, and mentions. Rewards can also come in the form of rankings on leaderboards (like the MindTouch one I wrote about), or invitations to speak at conferences. Did you know that in my 8 yrs as a technical writer, I’ve given 50 different presentations at various tech comm events — almost always due to the visibility from my blog? It’s especially fun to get invited to places like Vienna or Manchester.

Rewards for the Rewarder

The commenters themselves experience a bit of a rush in the comment. The commenter gets to interact directly with the article author, adding his or her thoughts and name to the actual page — and then usually receiving a personal response from the author. In this respect, both the commenter and the author reward each other, which drives up the success and repeatability of the activity.

This interaction through comments taps into our motivation for social connection, which is one of the major human motivators.

Meaning

Blogging also helps us achieve feelings of meaning and validation. If your writing resonates with someone, changes someone’s view, or provokes new critical reflection, it makes your activity feel meaningful. The inherent meaning provides value to the activity that other activities, like chores, sometimes lack.

Strategy

Blogging involves strategic components as well. You can increase your comments by engaging in a variety of techniques. You can research your metrics to see what topics are drawing the most visitors. You can employ tools like Hootsuite to push your new posts across more social channels.

One blogger I know once promised his readers that for each comment, he would read the commenter’s latest blog entry (if the commenter had one) and leave a comment on the person’s post. (This wore him out but skyrocketed his comment count.)

You can also search engine optimize your architecture to maximize your visibility.

In short, there are lots of strategies to increase the rewards you receive.

Pitfalls to Avoid

Just like any video game has pitfalls and other evils you have to avoid (think ghosts with Pac-Man), blogging has pitfalls. Comments are rewarding, but spam is annoying and sometimes crippling. You have to take measures to protect yourself from spam attacks, using plugins such as Akismet. You have to secure your blog from hackers and other malicious viruses.

Just as comments provide high moments of reward, they can also undercut you. Negative comments that tear apart your logic and reasoning may leave you feeling upset. When no one comments, it can be demotivating as well.

Other comments or pingbacks may actually misinterpret your main points, leaving you feeling frustrated.

Conclusion

I hope you can see how blogging makes a game out of writing. It’s easy to see why blogging has taken off, with millions of new blog posts a day. Meanwhile, those college compositions that you handed in to your writing teacher for an A, B, C, or D grade have become a thing of the past.

What’s cool is that, unlike chores, the game mechanics of blogging aren’t explicitly injected to incentive the activity. It’s not as if English teachers sat around thinking, let’s see, what can we do to make writing fun? I know, we can add an elaborate web architecture with an interactive comment system integrated into a self-publishing platform and social networks to share the material. The game mechanics are natural and fully integrated into the activity, which is why blogging is so successful.

Sponsors

• Open Help Conference
• Docutools
• 3Rabbitz book
• Southern Polytechnic: Information Design and Communication
• Simplified English
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite 4
• Plagtracker: Plagiarism Checking Service

I’ve had varying reactions to this report for the past several years. The first year MindTouch released the report (2010), I thought it was an ingenious marketing tactic. Within days after the initial release, the company had scores of bloggers inserting the badge on their sites, displaying MindTouch and linking back to MindTouch.com.

Last year it was pretty exciting to move from the #2 to the #1 spot. A colleague at work who learned about the report asked if he could relay the info in an all-hands meeting at work. It was kind of an exciting moment, during the announcements, to hear my name read and have so many people clapping on my behalf. That moment lasted exactly 8 seconds and then was never to be repeated again.

(Later that day I was asked to modify my About page to remove any specific numbers about the size of the company and to instead refer to it as a “large organization.” )

One of the product managers I worked with was pleased to have a new nickname for me, and for the next year (ever since I left, actually), he always referred to me as the “#1 blogger in the world,” despite my constant correction that it was only within the techcomm space, which happens to be pretty small.

This year when the report came out, I started to get more curious about it. Why was I ranking #1 for two years in a row, especially when some other people whom I feel are more influential than me don’t rank nearly as high? Was there something askew in the report?

How the Report Is Generated

The first year they compiled the report, MindTouch used its own formula for influence, one involving “a weighted average across a range of metrics including Alexa, Klout Influence, Google Page Rank, Technorati Authority, and Twitter Followers.”

But for the past two years, MindTouch has used Little Bird to generate the report. Little Bird is a Twitter analytics engine that uses an algorithm to rank top insiders around a keyword. It then lists these top insiders by rank.

I wanted more clarity into the Little Bird algorithm, but this is all Little Bird reveals about how they compile the top insiders:

Little Bird “Insiders” are the most connected people within a larger group found for a topic.

How are Little Bird Insiders found? We spider out across connections from the Seeds in your topic query to build an index of Insiders, then we see which insiders are most followed by others in the index. Top influencers are the insiders followed by the most other Insiders. Little Bird doesn’t pick the leaders, they are picked by their peers in a topic community! (What Are Little Bird Insiders?)

Let’s unpack that a bit, as I interpret it. Let’s say 1,000 people on Twitter use the word #techcomm in a tweet at least 50 times each year. We’ll call this group of 1,000 the #techcomm insiders. Within this 1,000 insider community, who is followed most? Counting up the follows, person T is followed by 366 other #techcomm community members, person S is followed by 357 #techcomm community members, person B by #350 #techcomm community members, and so on. The number of followers within a specific community determines your rank. Person T is ranked #1 most influential.

I can follow that calculation, but there’s another bridge to cross: How do you go from being the most followed to being the most influential? Does following someone entail being influenced by the person?

Equating following with influence might be a bit of stretch. When I think of influence, the people I follow on Twitter don’t come immediately to mind. People who have influenced tech comm tend to be people who have proposed new modes of writing (e.g., minimalism, DITA, topic-based authoring), people who organize tech comm conferences, people who teach tech comm in the university, or people who publish tech comm books advancing our knowledge. (I haven’t done any of that.)

Still, the people I follow do have some influence on me. Little Bird expands a bit on their method to justify it:

If I’m looking for top experts and influencers in the field of Neuroscience, what matters most is how many other neuroscience experts pay attention to someone I’m engaging with. …

Connections out of context, or even absolute popularity with the general public, are not the best way to evaluate someone’s influence in a particular field.

We believe that in-group validation is the best metric. It’s made even more valuable because it cannot be gamed, or cheated. There’s no way you’re going to win the attention of a whole bunch of neuroscience leaders without being pretty darned interesting. Thus, working backwards, seeing who has won the attention of a bunch of neuroscientists is a good way to find out who neuroscientists find interesting. (Social Media Influence Isn’t About Popularity, It’s Contextual)

In other words, it wouldn’t make sense to follow someone unless the person says things you find interesting.

Now we have another factor that leads to influence. If you say something interesting, you get followers. If you get followers, you have influence.  So all you have to do to influence others is to say something interesting.

As you can see, that logic is a little thin. I could say lots of radical, innovative, and interesting things on this blog without influencing someone to follow those thoughts. And actually, I often do take a controversial position, even just to explore the perspective.

In this regard, I have an advantage being a “nobody.” If you’re in a highly visible position, such as a company president or an organization leader, you have to be moderate [boring] to avoid offending people. If you’re a vendor or consultant, you often have to restrain your tongue as well, since anything you say unavoidably represents your company.

But when you’re a tech writer in the trenches, blogging as an independent voice not attached to an organization, tool, or company, you’re free to comment more candidly and occasionally say interesting things … which gets you followers … and influence.

Trying the Little Bird Report Yourself

You can get a beta login for Little Bird and run some reports yourself.  Here’s a screenshot showing the report interface.

You can see that if about 10 more top insiders would follow Sarah O’Keefe, she would displace me and take the #1 spot. (Ssshh, don’t tell her.)

In looking at the report, you’ll notice see a big factor in the ranking: Twitter. If you’re not on Twitter, then I’m sorry, but you will not rank well. Everything is based around who follows whom on Twitter. (Sorry Facebook, Google+, Linkedin, Pinterest, Ning, Tumblr, Vine, Orkut, and the hundred other social media networks.)

Here are a few other ways Little Bird sorts the insider community. These other categories are interesting even though they don’t factor directly into the top insiders list.

Number of Followers. For Little Bird’s algorithm, it doesn’t matter how many Twitter followers you actually have. For example, @karenmcgrane has a lot more Twitter followers than me (about 11k more), but she’s not a top #techcomm insider. What matters is how many top insiders in your keyword community follow you.

Number of Tweets. It also doesn’t matter how many times you tweet. For example, @rgoldstand, who posts an average of 37 tweets a day, doesn’t have the density of top #techcomm insiders following her to lead to a high rank.

(Actually, I’d even say that tweeting too much can be detrimental, as it may prompt a top insider to stop following you.)

Date You Joined Twitter. The date you joined Twitter account is included in the report. I joined Twitter quite a while ago (2,200 days ago, according to the report). That’s why I guess “tomjohnson” was available. (Some day I will sell this Twitter name to the Tom Johnson Camping Center, whom I’m sure would love to use it.)

The report also includes lists for emerging insiders and listeners. You can check out Little Bird for more details about those categories.

Is Following People Passé?

When I joined Twitter, it was during the Twitter era when everyone was following people. After a certain point in my Twitter timeline, I grew tired of following people. I found that looking through the stream of tweets of all those I followed was a chore. Trying to sort the relevant from the irreleant proved too slow.

Instead, I started paying a lot more attention to the #techcomm hashtag.

If I have anything to say related to techcomm, I add #techcomm to my tweets. And I think this factors into why I rank so high. If I regularly add #techcomm to my tweets, I attract more followers interested in #techcomm. I become a specialist Twitterer rather than a generalist, attracting specialists (i.e,. insiders) rather than generalists.

But if everyone follows this trend, that is, following hashtags more than people, it does complicate Little Bird’s algorithm. I asked Little Bird whether this behavior throws a monkey wrench into their algorithm. They said the general trend is still for people to follow specific people, but if this trend changes, they may consider integrating other factors.

Small Number of Top Insiders

It’s interesting to note that there are only about 500 top insiders in tech comm. This gives more context to the top #400 insiders that MindTouch published last year. It would be good to know exactly who all the top insiders are. Are you a top insider? How do you even check?

Little Bird does have a comparison feature. You can type in a Twitter name and see how many insiders follow the person, and how many people the insider follows. You can also export this data in a spreadsheet, but it’s a paid report.

Quantifying Online Influence

I mentioned earlier that I didn’t think much of the most influential report the first two years. It was kind of cool, but nothing huge.

However, when I was looking for a new job, being able to put this rank on my resume proved to be a major advantage, because it helped qualify the value of my blog.

Nearly everyone has a blog, but I could note that through my blog I was the most influential in the #techcomm space. Even if the report was problematic, it certainly helped me in the job market.

Using My Influence

One question I have is how exactly to use my position as an influencer to influence something. I don’t have any premeditated agendas. I’m not a vendor. I’m not a consultant. I don’t want you to buy anything from me except advertising. For a while I did WordPress side jobs, but I’m mostly phased that out. I also do podcasting now and then, but I’m never quite sure how much effort to apply in that direction.

Some days I think I’d like to write a book. But then I look at all the books on my shelf I haven’t read and rethink that idea. Other times I dream about inventing a new style of writing. Other days I’m just content to write about 1,000 words about any topic I consider interesting.

Wrapping It Up

Overall, although I’d like to say that being the most influential means nothing to me, it does give me some satisfaction (even as flawed as the report is). I’ve only been a technical writer since 2005, and during that time I’ve enjoyed an immense amount of visibility and readership.

It pleases me to know that my posts or tweets are sufficiently follow-worthy.

If you’re a top insider, thanks for following me! If you only follow my RSS feed, consider following me on Twitter too. Otherwise I’m not really influencing you.

Postscript

For another viewpoint on the report, check out Miriam Lottner’s Sour Grapes of #Techcomm post.

Sponsors

• Open Help Conference
• Docutools
• 3Rabbitz book
• Southern Polytechnic: Information Design and Communication
• Simplified English
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite 4
• Plagtracker: Plagiarism Checking Service

The movement towards disorganization describes the natural direction of many things. Our houses get messy each week and must be cleaned. Our computer desktop gets cluttered and must be ordered. Broken eggs don’t naturally reconstitute themselves into whole eggs. Sand (which was once rock) doesn’t reshape itself into rock.

Content also resists order at every turn. Even when you have multiple contributors working on the content, you can still end up with a content mess, something that’s no better than the metaphoric broken egg or random whirl of sand. In fact, the more contributors you have shaping the content, the more problematic it often gets.

Single Person Authoring

When one person writes an entire body of technical content, the content tends to be more organized than scenarios in which multiple writers contribute to the content, especially when the multiple writers come from different departments, writing at different periods in the company’s time, with different writing backgrounds and skill levels, and with a variety of styles.

Yet while single author paradigms sometimes result in tighter coherence of content, the single authoring paradigm doesn’t scale and tends to be myopic. Content authored by just one person gets outdated and is often incomplete. Modern workplaces can’t discard collaborative authoring and still keep pace in the market. So let’s examine three scenarios to explore how collaboratively authoring goes awry, resulting in a content mess.

Scenario 1: Avoiding Offense

Tina, a technical writer, writes 50 pages of documentation on the company site. A year later, Mark in Marketing comes along and writes another 50 pages. Mark doesn’t want to remove the content Tina wrote, so he recreates some of his own in another section of the site with his own navigation.

Sue in Support adds 25 more pages, following a different style than anyone else. Sue leaves the other content alone for the most part, tacking hers on as an addendum. Then Bill, a business analyst, enters the scene and tries to clean up some of the content, but ultimately just shifts it around to other sections and finds space to insert his own.

This is how you end up with a content mess. Everyone adds their own content without seeing and shaping the content as a whole.

This scenario happens frequently with wikis, which is why wikis often degenerate into content junkyards. But it can also happen wherever you have a collaborative authoring scenario.

The basic problem is that content contributors are too kind. Rather than slashing and burning the forest to regrow the trees, they instead plant new patches of forest here and there in their own little areas, and then wonder why the landscape looks like a jungle.

Scenario 2: Too Much Control

Now let’s tweak the variables a little. Tina the technical writer creates 50 pages of content in a help authoring tool (e.g., ACME Builder) and publishes it in a tripane help. Later Sally needs to add another 50 pages. But Tina is the only queen in her kingdom, and doesn’t allow outsiders to have tool control, so Sally decides to publish her content on a Google Apps site instead.

Jane has a need to push out 15 more pages, so she pushes it onto her own platform she can control — a self-hosted open-source wiki (Confluence). Mark then enters the picture to publish some more extensive information on yet another platform — a WordPress site.

In this model, although each writer creates content on a separate platform, the result is the same content mess, only fragmented across platforms and tools. Sure it’s more organized, but no one can find anything because they don’t know which site to explore.

Different employees have different publishing needs, and if you stop a group from writing and publishing, they just find their own tool and venue to get the content out. Consistency of tools, both with access and authoring, poses huge challenges with collaborative authoring.

Scenario 3: Process-driven Collaborative Authoring

In my third scenario, the tech pubs group has a tight process to control who can author and publish content. Tina the technical writer creates 50 pages of content. She learns that Sally in Support has a lot of information to get out to customers, so she meets with Sally and edits her content as she integrates it into the existing content.

Tina also learns that Jane in Development has new information to add and has already written it. Tina modifies the information and integrates it into the existing technical content. She does the same with Mark from Marketing and others who have content to publish.

In this model, Tina is the gatekeeper, the editor, and the publisher of content. She carefully integrates the content into the same platform, enforcing judgment about what to cut in order to integrate content in a logical way.

This third model seems to work best because it empowers someone as a content steward. Any site that’s going to maintain a coherent and consistent structure needs someone to oversee who adds what and where. Like a soccer game, a content-rich website need a site referee to blow the whistle, hand out yellow cards now and then, and keep order on the field. This person is known as the “chief content officer” in some circles.

The only problem is that as a content referee, Tina has no time to play the game herself. The CCO role takes the most skilled writer in the company and displaces her from an individual contributor position. (Of course, this practice follows standard corporate “growth” models. See the Peter Principle for more details.) The writing quality degrades because there are fewer skilled writers creating content.

Although the content CCO model seems most compelling, it gets more complicated. How does Tina entitle herself as a content gatekeeper and gain authority to prevent others from self-publishing? How does Tina keep up-to-date about all the content publishing needs the organization has without attending nearly every single meeting? How does Tina find time to verify the information coming from other groups? If she doesn’t verify the information, what happens to the writing quality?

Ideally Tina needs some technical privilege that entitles her with a Publish button but restricts the button from everyone else. But in order to get this kind of privilege, she has to entrench herself in department politics and strategic maneuvering, usually while keeping up on all her writing and publishing duties. This will spread Tina’s time rather thin as well as increase her pressure to perform. The scenario takes the writing out of the writer.

A Final Scenario

There’s one final scenario to present: doing nothing. In Scenario 4, Tina authors 100 pages of content, completes her contract with the company, and then leaves. Meanwhile, developers continue to push out new releases, designers modify the interface, users identify gaps and other problems, QA testers find bugs and quirks.

Pretty soon, after about a year, the documentation Tina once wrote, which looked so complete and helpful when she first published it, is now an outdated mess.

Conclusion and a Light in the Tunnel

None of the scenarios are ideal, which is why content so often unravels from a state of order to a state of non-order.

I mentioned at the beginning some commonly held thoughts about entropy, noting that the natural direction of the world moves toward disorder, including content. But that’s not entirely true. Planetary dust does swirl into ordered planets. Molecules assemble themselves into intelligent, living helix formations — all without seeming to have a guiding hand. Content might have a natural destiny that it shapes to, some property that language innately contains that leads it to an intelligent formation. But I doubt it.

Sponsors

• Open Help Conference
• Docutools
• 3Rabbitz book
• Southern Polytechnic: Information Design and Communication
• Simplified English
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite 4
• Plagtracker: Plagiarism Checking Service