I'd Rather Be Writing » information architecture

Podcast: A Practical Guide to Information Architecture, with Donna Spencer

Tom Johnson — Fri, 18 Mar 2011 06:25:21 +0000

A Practical Guide to Information Architecture

Donna Spencer is the author of A Practical Guide to Information Architecture as well as two other books (on card sorting and writing for the web). She’s an experienced information architect, based in Australia, who gives regular workshops on information architecture at conferences such as the IA Summit and also runs the UX Australia conference. In this podcast we talk about information architecture, especially in the context of technical communication. Some of the topics we cover include the following:

What information architecture is, especially in contrast to content strategy and user experience
Why writers are well suited for information architecture
Reasons for doing user research prior to building your information architecture
Determining user terminology (and dangers of choosing the wrong terms, even if people use them)
Evaluating browse versus search, and the problem of looking for information without knowing the right terms
Strategies for dealing with overlapping categories and difficult-to-fit topics
Why organizing content by audience can be tricky
Using focused entry points to serve different audiences
Finding what you need when you don’t know what you need
Organizing content by popularity, and other alternative classification schemes
Scenario driven testing with index cards
Card sorting strategies, tools, and limits
Reasons for brainstorming IA off-screen, without your computer.
Determining the number of top-level navigation options
Providing navigation through next and related links
Beginning the information architecture at the content page rather than the home page
The kind of content to add to your home page

I highly recommend this book as well as learning more about information architecture in general. For more information about Donna Spencer, see her site, Maad Mob. For more information on her book, see A Practical Guide to Information Architecture. You can follow Donna on Twitter @maadonna.

Blog Sponsors

Arguments for and Against Tripane Help

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

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

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

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

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

Cons of Tripane Help

Let’s start with the cons of tripane help.

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

Rest in Peace, Tripane Help

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

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

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

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

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

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

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

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

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

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

Pros of Tripane Help

Now for the pros of tripane help.

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

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

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

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

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

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

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

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

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

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

Conclusion

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

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

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

Blog Sponsors

Implementing Faceted Classification/Search with a Help Authoring Tool [Organizing Content 7]

Tom Johnson — Fri, 21 May 2010 15:24:55 +0000

In my last post, I presented faceted classification and faceted search as an alternative method of organization for help content. While faceted navigation systems are common on the web, implementing a faceted navigation system to describe help content using one of the common help authoring tools, such as Flare, RoboHelp, Author-It, Doc-to-Help, is more challenging.

Faceted Browsing

According to Tony Self, one of the strengths of a help authoring tool (HAT) is the table of contents (TOC) feature. Through the TOC, you can easily create a quick system of navigation.

It’s common to use this TOC to create a system of topic-based containers for users to navigate, but there’s no reason why you couldn’t instead dedicate the folders to facets. In the prototype below, each of the “Browse by … ” books in the left pane represents the facets by which users can navigate the help content.

Faceted browsing system showing alternative methods of navigation

Users can browse the content by the following facets:

Browse by Topic. Topics are arranged in the traditional topic-based, hierarchical containers.
Browse by Role. Topics are arranged by role (super agent and regular agent), and then broken down by topic containers.
Browse by Skill Level. Topics are broken into two books, Advanced and Beginner. And then most likely broken down by topic containers.
Browse by Popularity. Only the top 20 most popular topics are listed.
Browse by Concept or Task. Topics are divided into concept and task groupings, and then probably broken down by topic containers.
Browse by Status. Topics are organized by facet. (In Swordfish, statuses play a prominent role for operations. Depending on the status of the operation, you can perform certain tasks, so this provides a way to organize the tasks.)
Browse by Help Format. Topics are divided into video, diagram, and FAQ groupings.
Browse by Problem. Topics are arranged by problem, somewhat like a troubleshooting grid.
Browse by Screen. Topics are arranged by screen. These are the context-sensitive help topics.

Almost every HAT allows you to create multiple TOCs. Each of these facets is simply a secondary TOC that is integrated into the master TOC.

One of the problems with these facets is that they don’t entirely get away from the topic-based containers that I am resisting. With 200 topics, I can’t simply divide all topics in the help into two groupings, such as Advanced and Beginner. A second tier facet is also necessary, and the only second-tier facet that makes sense is the topic container.

However, some inclusion of topic containers isn’t necessarily a bad thing. The main reason topic containers fail is because of the abundance of topics. In small help systems, the topic containers provide easy navigation and aren’t as frustrating for users. The first facet, such as Advanced or Beginner, breaks down this large number of topics into a smaller subset, which makes the navigation more feasible.

Faceted Search

When a user clicks the search tab and searches for an item, the user can narrow the search results by using similar facets, as shown in the following image.

Faceted Search

I’m not sure how it would be implemented in other HATs, but in Madcap Flare, you can tag each topic with a keyword (this is called inserting Concepts). You can then add this set of tags/concepts below the search box by adding a “Search Filter Set” to your help.

The challenge here is to provide the same facets that users get by browsing. Tags work a bit differently than TOCs, but the idea is the same. You can limit the search results by the following:

Regular Agent Role
Super Agent Role
Advanced Level
Beginner Level
Conceptual Topics
Step-by-Step Topics
Most Asked About
Video Format
Diagram Format
FAQ Topic

Not all of the TOC facets end up as tags. The Browse by Role facet has two roles, so I can tag topics within these books as either a Regular Agent Role or Super Agent Role.

The Browse by Skill Level facet has two levels, Beginner and Advanced, so I can tag the topics within this facet as Beginner Level or Advanced Level.

For the Browse by Concept or Task facet, I can tag the topics as Conceptual Topics or Step-by-Step Topics.

The Browse by Popularity is tagged as Most Asked About (or Most Popular).

Finally, the Browse by Format allows me to tag the topics as Video Format, Diagram Format, or FAQ topic (these are the only three main formats in the help material apart from the concept/task distinction).

Shortcomings of Faceted Search

One of the most difficult problems with setting up faceted navigation is to identify facets for information topics. With merchandise or other products, you can often identify a clear set of attributes that define the product. With shoes, you can classify and filter the shoes by brand, style, color, cost, gender, sport, size, and other qualities.

With Google, you can classify the content by a plethora of information formats, including news, books, videos, images, maps, discussions, shopping, blogs, twitter (“updates”), and more.

In a library, you can classify books by author, publication date, genre, period, subject, book type, etc.

Help topics don’t seem to have a set of clearly identifiable facets. Some of the facets that you could classify a help topic with — for example, length, format, reading level, information type, corresponding screen, etc. — aren’t that helpful to users.

Help content is, however, rich in topics. But using topic tags as the attributes seems like the same game as the topic-based, hierarchical containers. For example, look at the faceted search filters that I’ve circled in the following image.

Topic facets on a search for a topic

If a user searches the help for “run a black operations campaign,” what benefit is there in limiting the results to the facet “Related to black ops”? Won’t the results already contain black ops topics?

Further, what if a user searches for “coordinate informants for black ops”? Which facet would I then choose to limit the results — Related to Black Ops or Related to Informants? It’s the same problem as the topic-based, hierarchical containers.

Searching for a topic and then limiting the results by topics seems redundant to me.

Moreover, if these facets are simply topics, there’s a likely chance that you’ll include dozens of topics. Adding too many topics in the Search Filter Set will bloat the number of search facets beyond what is usable. If you look at the search filter set in Flare’s online help, you’ll see that they use about 80 different topics in their search filter set, which seems excessive.

It’s clear that faceted classification and faceted search have benefits for many product websites, as well as for many information-heavy websites with many types of content. But the lack of a clear set of facets for help material makes it more challenging to implement in a way that is clearly beneficial.

Blog Sponsors

Introduction to Technical Writing (podcast)

Tom Johnson — Wed, 25 Mar 2009 01:00:33 +0000

Download MP3 (to download, right-click and select Save Target As)
Length: 43 min.

In this podcast, I talk with Ricardo Amigo, a translator and podcaster in Mexico City and Costa Rica, about the field of technical writing. This podcast is more of a reverse interview. Instead of me asking the questions, Ricardo interviews me. The general topic is the field of technical writing, including all of the following:

My path into technical writing
Structured authoring
XML and DITA
Information architecture
Usability — for documentation and software interfaces
Publication formats for help material
Breaking into technical writing
Tools for help authoring
The growth of technical writing
Creativity and technical writing
A typical day as a technical writer
Translation techniques and tools
Simplified technical English

Ricardo’s company is called Amigo Audio, and they principally do translation. For example, if you need your manual or software interface translated, Amigo Audio can help. You can contact Ricardo Amigo at sinpapel@yahoo.com. Additionally, you can read more about their translation services at Amigo Audio.

Blog Sponsors

Podcast — Transitioning from Technical Writing into Usability

Tom Johnson — Thu, 03 Apr 2008 05:25:00 +0000

Download MP3 (right-click, select Save Target As)
Duration: 30 min.

In this podcast, I talk with Theresa Putkey, a usability consultant in Vancouver, about how she transitioned from technical writing into usability. This is part II of the previous conversation with Theresa.

Learn more about Theresa by reading her blog. You can also read Theresa’s articles on Boxes and Arrows.

Topics in this Podcast

In this podcast, we talk about the following:

How to move into usability
Designing user interfaces
Contributing towards usability on project teams
Compelling reasons to transition from technical writing into usability
Whether applications can be so intuitive that they never need manuals
Conjectures to the question — Will technical writers ever be extinct?
Making content more findable in search
Tagging topics with concept keywords to increase their search rating
Harnessing related topics, concept keywords, and synonyms for search results
Browsing in the table of contents versus relying on search to find content
Making content findable in large projects (such as those with 3,000+ topics)
Using card sorts to determine user terms for topic names
Using focus groups to gather terminology and function lists from users
Usability consultant versus technical writer — preferences, purposes, and job satisfaction
Whether technical writing is only a transitional field
Defining different categories within user experience: interaction design, graphic design, programming/web designer and programmer, information architecture (designing information spaces)
Creating navigation that people can use to find information
Expanding beyond user interface when it comes to usability
The Information Architecture Institute (IA Institute)
Content Management Professionals
IXD, Interaction Designers Group
Human Factors Group
Vancouver User Experience Group (VanUE)
Organizations and professional groups for usability
Choosing your career — technical writing or usability?
Teambuilding, including everyone, and communicating regularly
Building relationships in your company (the key to success)
Collaboration, teambuilding, and communication — breaking down silos across departments
Techniques for bringing people together (the importance of the watercooler)
The paradox of making friends and winning people to your side

Note: Ever wonder why I make such an extensive list of topics covered? Audio doesn’t have keywords like blog posts, so people who search for them on Google never find the audio unless I saturate the show notes with relevant keywords.

Podcast Sponsors

MadCap Flare is the most versatile XML-based Help authoring tool on the market, with thousands of customers using MadCap products including Microsoft, Google, HP, GE, yahoo and the list goes on. Check out Flare version 3.1 and a host of other new tools at at madcapsoftware.com.

Adobe – The Technical Communication Suite software offers a complete solution for authoring, managing, and publishing interactive instructional information from technical documents and books to online help systems, knowledge bases, interactive training, and eLearning content in multiple formats and languages. Learn more here.

Intro music is Velveture by Ocean Alexander

Upcoming Training on WordPress

Are you interested in learning more about self-hosted WordPress blog sites? If so, let me know by sending me an email (tomjohnson1492@gmail.com). I’m planning to offer some training in the upcoming weeks. Training will cover everything from the basics, such as using posts, pages, categories, and tags, to PHP calls and CSS tweaks.

Information Architecture: Organizing Chaos, Metadata, Taxonomy vs. Folksonomy, and the Dublin Core

Tom Johnson — Fri, 22 Jun 2007 01:52:33 +0000

Download MP3 file
Duration: 27 min.

In this podcast, I talk with Kevin Shoesmith about information architecture and the challenge of organizing complicated websites. Kevin explains about the importance of metadata, providing user-driven organization, taxonomy vs. folksonomy, the Dublin core, the usability of web menus. Music from Podshow. Check out Kevin’s blog.