“Bake your taxonomy” workshop at #tcuk13

Knowing your audience, their needs and use cases is key, not only when writing documentation, but also when designing its topic structure, navigation structure and taxonomies. That’s the insight  around 50 participants came to at the end of the “Bake your taxonomy” workshop which Chris Atherton and I facilitated at the first day of TCUK13 in Bristol.

The insight itself is not revolutionary, of course, but it gave attendees a chance to try out content modelling and card sorting first-hand and consider alternative designs and difficult decisions that go into structuring documentation just right.

Explaining taxonomies and content models

Chris and I started the 3-hour workshop with a 30-minute presentation:

Organically grown content often develops into a mess of good, bad and ugly content with little or no discernible structure. An information architecture that was designed by central oversight and with a guiding higher principle might resemble a cathedral – but the organically grown reality more often resembles a bazaar.

Both models have their drawbacks: The cathedral might be out of touch with what users need to do and know in their daily lives. The bazaar supplies that better – but it’s much harder to navigate, unless you know it really well.

Chris and I presenting (photo by @JK1440)

Enter taxonomies, which are hierarchical classification systems. Just as children and veterinarians use different systems to distinguish and classify animals, so users and we who write for them can distinguish different topic types and structures and different ways to navigate topics according to their needs and use cases.

Exercises: “Bring out the scissors!”

Then we formed 12 groups of approx. 4 and set off on a couple of exercises:

• Content modelling. Take a documentation set (in our example a user manual for a handheld audio recorder) and develop topic types and content models for users, their needs and use cases. Then re-chunk the manual into new topics according to topics types and users.
• Card sorting. Take the topics and find the best sequence and hierarchy for them.  Also consider the documentation format such as print, online, etc., and topic re-use opportunities between different formats and use cases.

Workshoppers baking their own taxonomy (photo by @JK1440)

After the first exercise, we had a short roundup of the different approaches and results of the groups and a short break, before we embarked on the second exercise.

As it turns out, it’s really difficult to separate between content modelling (structuring within topics) and card sorting (structuring of topics). And in many cases there might be few benefits to separate those tasks. However, if you do the content model first and in isolation, you might have a more stable content model that lends itself to more than the structure you’ve used to pour it into.

To sum up, it was a very lively workshop with many good discussions – mostly within the groups of four, but also in the roundups when we collected approaches and insights. Chris and I thoroughly enjoyed it and learned a lot about what a diverse bunch not only tech comm audiences, but also we as practitioners can be.

If you’ve attended the sessions or want if to know more about what happened and how, feel free to leave a comment.

Advertisement

Top 3 fixes when editing topics

A few recurring issues distinguish the editing of structured topics from that of other content. Here are the top 3 issues I’ve recently found while editing topics for language, consistency and structure.

1. Topic heading is weak

A heading can seem appropriate when you’re writing the topic, but it may still seem weak when you see it in the context of the entire help system, for example, in a list of search results.

Write topic headings so they give your readers a precise idea what that topic is about. Yes, that can be challenge when you’re trying to be precise and concise at the same time:

• Indicate what kind of information a topic contains. For task topics, consider starting the heading with an imperative verb. For concept topics, consider using noun phrases.
• Offer enough context so your reader can identify what area or functionality in the product the topic refers to.

2. Purpose or user benefit is missing

A topic can look great and complete: It does whatever self-contained thing it set out to explain. But if it doesn’t also contain a why and wherefore, it’s harder for the reader to understand whether they’ve come to the right topic and how it helps them.

Include the purpose or user benefit of whatever the topic describes early on, in the first or second paragraph. Answer the readers’ potential questions:

• Why is it important to know about or do whatever the topic describes?
• How does this connect to my work?
• How does it make my job or my life easier?

Be careful to describe the purpose or benefit of the topic’s content, for example, the actual concept or task, not the purpose of the topic. Focus on: “This function helps you…”, not “This topic tells you…”

3. Topic mixes topic types

A topic can look complete, comprehensive, and self-contained, but if it goes overboard and describes both, functional tasks and underlying concepts at length, it tends to overtax the patience of those who only need to know one of the two. It also makes it harder to assign a clear heading, to structure the topic clearly and to reuse the topic in additional contexts you might not yet know about.

Stick (mainly) to one topic type per topic. If you’re using the traditional triad of concept, task and reference topics, divide them accordingly, but keep it pragmatic. Ray Gallon and Mark Baker have both shown how a little conceptual information in task topics can go a long way, but they shouldn’t replace entire concept topics. Also see my previous post When topics don’t quite work from two years ago.

Summary

These top 3 issues and several others basically have the same underlying reason: We tend to write topics in the context of a function or a window, but that context is not necessarily familiar or identifiable to our readers.

Issues with the same reason also share the same basic solution: We should focus on writing topics in the context of our readers, their environment and their tasks in it.

Techcomm lessons from UXcampCPH barcamp

Two big lessons I take away from attending last week’s UXcampCPH, Copenhagen’s “un-conference” on user experience, are:

• Tech comm’ers and UX’ers can and should join forces because we have essentially the same goals.
• Barcamps can be a fantastic alternative to conventional conferences.

While the 270 attendees were a mixed bunch, to be sure, I met only about a handful of technical communicators like myself. So what was it like to be a tech comm’er among hundreds of UX professionals, graphic designers, information architects, web designers, etc.?

Barcampers hanging out between sessions at Copenhagen’s IT University; photo by @andersmn

So close, and yet so far apart

I frequently heard the question: What does a technical communicator actually do? The answer “Write documentation” proved confusing because that meant to some the documentation of a UX project. “Writing user manuals and online help” was satisfactory, but apparently not an obvious answer…

That’s a pity because at heart UX and tech comm share a gommon goals: We both make products mean something to customers. We just do it in different ways: UX’ers design the actual experience. Tech comm’ers help the user along with additional instructional, background, and technical information, when necessary.

If tech comm’s user assistance is embedded in UX’s user interface we actually blur the boundary: User assistance can start with UX field labels and progressively disclose more documentation via tool tips to a full-blown help system.

We even have an external reason to join forces as we both occasionally suffer from similar misperceptions when it comes to the value we add. The varieties of our achievements often goes unnoticed outside our respective fields, as the cliché goes: “Everyone can draw / write…” 🙂

What makes a barcamp special?

A barcamp tries to avoid many of the hierarchical pitfalls of conventional conferences. It emphasizes participation and networking over listening and consumption. The general motto is “You are the barcamp” – and the program is built at the beginning of event when potential speakers pitch their ideas for sessions. Depending on the number of votes from attendees, speakers get a spot on the program.

At UXcampCPH, everybody got to speak: Of approximately 270 participants, there were only 16 pitchers for the 24 session slots. The event was a bit special in that they invited 3 keynote speakers – which often isn’t done at barcamps to stress the egalitarian, participatory vibe. But in Copenhagen, the keynotes worked well by bringing everyone onto the same page (see my previous post of session summaries).

UXcampCPH participants pitching their sessions; photo by @JohannaBlomgren

Here’s how I would compare features:

Conferences vs. Barcamps

• Primary tool: Laptop vs. iPhone
• Communication artefact: Business cards vs. twitter handle
• Networking over drinks opportunity: Drinks reception vs. pitchers of beer
• Food: Banquet buffet vs. organic soup kitchen
• Location: Conference hotel/convention center vs. university lecture halls
• Sponsors’ presence: Trade exhibition vs. brand exposure via room names & swag

If you know more reasons why tech comm and UX should join forces – or what distinguishes barcamps from conferences – feel free to leave a comment!

Trying something new: UXcampCPH

This week, I’ll be trying something new: I’ll attend UXcampCPH, my first “unconference”, in a neighboring discipline, namely user experience.

How it’s new for me

Unconferences are new to me. Apparently, unconferences forego much administrative clutter, such as advance session programming and sponsored presentations, for a more grassroots approach of: “The conference is us!”

That means unconferences emphasize participation and networking. Attendees bring presentations they want to present and pitch them at the beginning of the unconference.

I’m expecting a good deal of “fly-by-the-seat-of-your-pants” attitude and possibly a glitch or two. Considering the occasional bust session I’ve caught at conventional conferences, I don’t think unconferences need to be worse on principle, though.

User experience (UX) is one of those neighboring disciplines that I bump up against in tech comm ever so often. According to the ISO definition, it means “a person’s perceptions and responses that result from the use or anticipated use of a product, system or service”. Tech comm brings practitioners, theory and research to UX, as Ginny Redish shows in the first part of the article “Overlap, Influence, Intertwining: The Interplay of UX and Technical Communication“.

Seeing how closely UX is connected to what we do in tech comm makes me regret knowing so little about it and wonder if I shouldn’t take it into account more. (Other disciplines which evoke similar reactions include usability, accessibility, content strategy, etc.)

Why I recommend trying new stuff

I have no idea how much I will actually get out of UXcampCPH. But I’m excited about the opportunity to participate for several reasons:

• Find out how UX people tick. Hanging out with them for a weekend will give me a good idea what’s important to them, how they approach their work and what they think of tech comm’ers.
• Include UX in my work. I’m hoping to get beyond my theoretical, distant understanding of UX towards a more practical grasp that can help me incorporate it better when conceiving and creating documentation.
• Spread tech comm goodness. In the second part of the article mentioned above, Ginny Barnum asks “Why should technical communicators claim a seat at the UX table” and endeavours to “stimulate technical communicators to join with UX specialists”. I guess some UX’ers might feel about tech comm the way I feel in reverse: They might know about it from more or less distance, but maybe not understand exactly what we do or how we add value. I’d be glad to point out where and how we can work together, each with our individual skills and talents.

Shameless self-promotion

I’ll be one of the tech comm guys. If you attend UXcampCPH and are wondering what tech comm does or why documentation can be so weird, feel free to talk to me.

I’ll be the pattern recognition guy. If you attend UXcampCPH, vote for me: I’ll pitch my presentation how we can apply cognitive processes to improve UX (and tech comm). Thank you!

Getting mileage from a tech comm mission statement

If you have a mission statement for technical communications, you can use it to anchor several strategic and tactical decisions. I’ve suggested a few general reasons Why you need a tech comm mission statement in my previous post. The valuable discussion that ensued led me to think we can get some mileage from a mission statement in some high-level tasks further downstream.

Consider a mission statement that says: “Our product help provides users with relevant product information at the right time in the right format.”

Defining audiences and deliverables

You can keep your audience in focus with a mission statement. Do you write for end users? Maybe there are different types, such as professionals vs. amateur hobbyists? Do you also address colleagues who expect to find internal information in the documentation? The mission statement above doesn’t specify it – and hence can be expected to address everyone who uses the product.

You can also derive your deliverables from a mission statement. Do you publish to several formats or only to one? What is your priority of formats? Web help first, PDF second seems a standing favorite that’s recently been disrupted by the emergence of mobile output. The mission statement above merely mentions the right format – so you need to figure out what format is right for your audience types. You can use personas to determine how your users work with the product – or better yet: Observe or survey them!

Defining information model and processes

You can derive your information model, the structural standard of your documentation, from your mission statement. This model should help you to reach the goal described in your mission and serve your audience. For example, topic-based architectures have long been popular. If you need to retrieve small chunks of information, for example to share steps in a task or exception handling advice, consider a more granular standard such as DITA.

Your processes should outline a repeatable, efficient and effective way to create your deliverables so they address your audience and, once again, help you to achieve your mission goal.

Your information model can suggest which topics or elements to create need to be created and updated for a given product or enhancement. Together with your processes, this makes it easier to plan and estimate documentation efforts – in theory at least…

– But with some management support and some persistence, a mission statement and some strategic decisions piggy-backed on to it can help you get out of the proverbial hamster wheel.

What do you think? Can this be helpful? Or is it too far removed from real life? Do you have any experience with a larger documentation strategy based on a mission statement? If so, did it work?

Why you need a tech comm mission statement

A mission statement for technical communication can help everyone in your company (or you and your customers) to stay on track in pursuit of a common goal of what your documentation can and should achieve.

Just like a corporate mission statement, a tech comm mission gives all parties who are involved with documentation direction and a common goal. It describes the purpose and benefit of the documentation and how it is achieved. It helps to define processes for creating the documentation as well as metrics whether the documentation is successful. If the mission is well-conceived, it guides documentation strategy without prescribing it.

For example, if you want to focus on usability and speed, a mission for your documentation could be: “Our product help answers any user question about product use in no more than three mouse-clicks.” Your strategy would then aim for a well-structured, easily navigable context-sensitive online help – with printed user manuals and closely tied in training materials taking a backseat.

A more comprehensive mission could be: “Our product help provides users with relevant product information at the right time in the right format.” This would set you on a quest to find out who your user types are, which product information is relevant for them and which formats it can be provided efficiently.

A mission statement in itself cannot be right or wrong. But it must be useful in several respects. Specifically, it must help:

• Your customers and users by guiding you to provide useful documentation.
• Your company externally to provide documentation which improves the perceived product quality.
• Your company internally to anchor the importance and function of documentation.
• You as technical communicators to make appropriate strategic decisions about documentation, for example, which users to address, which deliverables and processes to define, which methods and tools to apply.

What do you think? Is a mission statement for tech comm necessary? Or merely helpful? Or a vain attempt at putting on corporate airs when the writers should just buckle down and get the job done?

(Edit: The discussion continues in “Getting mileage from a tech comm mission statement“…)

EPPO redux or: Mark Baker is on to something

“For users, Every Page is Page One,” says Mark Baker. Users can land anywhere in your documentation and start consuming away. That’s why structured authoring is more than one method among many – it’s an imperative to create meaningful content and to stay relevant as a technical communicator.

Few technical communicators have recently chipped away at unquestioned conventional wisdom as profoundly as Mark Baker in his blog Every Page is Page One (EPPO). Here’s his thesis in a nutshell – EPPO redux, if you will.

The following is my boiled-down edit of the session description of Mark’s workshop at the Intelligent Content Conference yesterday. I can only claim credit for the mistakes and misunderstandings I introduced, but everything below is essentially Mark’s wisdom. I share it because I find it sensible and highly relevant – if you do, too, I encourage you to follow Mark on twitter and on his blog.

Writing Every Page is Page One Topics
Mark Baker, President, Analecta Communications Inc.

For users, Every Page is Page One. So write good Every Page is Page One topics, even when you have a large amount of related subject matter to cover. Construct information so readers can meet their information needs, no matter where they land. When covering a broad array of subject matter, don’t design the information to be consumed sequentially or hierarchically like a book.

Successful Every Page is Page One topics

• Define a limited purpose: Do one thing per topic, do it well and completely.
• Stay on one level: Be broad or be specific in a topic, but pick one and stick to it.
• Establish context: Orient readers so they know where they are.
• Conform to type: Orient readers so they know what type of topic they see, help the writer be consistent and complete.
• Assume the reader is qualified: To help readers get qualified offer links in a topic, not details.
• Link richly: Encourage the reader to explore, anchor the topic in its context.
• Provide the big picture: Create explicit high-level picture, don’t bury the big picture in the htopic sequence or hierarchy.

Address information overload in tech comm

Addressing information overload helps your user assistance succeed when knowing your audience and offering correct and concise content is not enough. You can have great topics well-written and well-structured, if they’re part of an information deluge, they won’t help your users get their stuff done.

I take my cue from a post by Nathaniel Davis over at UX matters called “IA Strategy: Addressing the Signatures of Information Overload“. Nathaniel describes six such signatures. I think at least three of them have something to say why and how too much information fails in documentation, too.

1. Feedback

Feedback is the essential reality check to determine whether users suffer from information overload. Customers may report that they’re not sure they’ve found the right information or they cannot apply it efficiently. Even if the content is fine topic by topic, the bulk of information is unmanageable. In this case, consider improving search and browsability for more efficient use of the documentation.

2. The utility gap

The utility gap means that customers only use a small fraction of all the information they have at their disposal. As Nathaniel says, it’s what I have vs. what I use.

If certain user types experience utility gaps, consider addressing them with special documents. For example, you could assist novice users with a quick start document. Or address a special use case which only requires one of the many processes, plus some reference information. With topic-based authoring, it’s usually easy to create such additional documents by re-using the relevant topics. (Maybe add one or two specific “glue topics” to make sure the new document still flows nicely…)

If all users experience utility gaps, consider progressive disclosure by layering your content. The benefit of offering all content within three mouse-clicks wears off if it’s too much. Progressive disclosure structures content by providing the most essential, most frequently used topics first and more obscure information later. Make sure, however, that all topics remain searchable and findable!

3. Filter failure

Filter failure means that users lack ways to judge which information to trust and use. It’s what I can use vs. what I should use. Filter failure can be solved with tools and with content.

Customers who are confident to use their own judgment require tools to filter information. In documentation, faceted search allows users to reduce search results by categories to weed out inapplicable information.

Customers who prefer to rely on expert judgement will benefit from recommendations in the content itself. Consider adding such recommendations for certain user roles or use cases to guide customers to the most suitable information.

– Have you had symptoms of information overload in documentation? Would these strategies help users to cope? What other solutions are there? Feel free to leave a comment.

How our addiction to meaning benefits tech comm

Join me for my presentation “Addicted to Meaning: How Good Technical Communication is Like Bad Magic Tricks” at tekom/tcworld in Wiesbaden on Tue 23 Oct at 1:45 pm.

In the session, I will explore how “meaning” works in technical communication, why it sometimes fails and how you can improve its chance for success. Being meaningful in your work is harder to measure than being correct, concise or consistent. However, it is just as essential: Understanding how and why communication is meaningful to your readers can help you to make your documentation more effective and to distinguish good from bad.

Using examples from topic-based authoring and minimalism, I will illustrate the underlying working of semiotics and mental models to show:

• Why minimalism works, but FAQ’s don’t
• Why asking a friend is effective, even when he doesn’t know the answer
• How readers create meaning from documentation
• … and how good documentation is like bad magic tricks 🙂

I will put our familiar tech comm tool box into a new context, so you can get a deeper understanding and a fresh perspective on tech comm and how it fits into the bigger picture of meaningful communication.

I’ve set up the topic in two earlier posts which give you an idea how I’ll tackle the issue:

• But do we create documentation with meaning?
• How meaning works in technical communication

Scott Abel on Structured Content at TCUK12

Scott Abel delivered his keynote It’s All About Structure! Why Structured Content Is Increasingly Becoming A Necessity, Not An Option in his usual style: Provocative, but relevant, fun and fast-paced (though he said he was going to take it slow). He even channeled George Carlin’s routine on Stuff: “These are ‘MY Documents’, those are YOUR documents. Though I can see you were trying get to MY Documents…”

His style doesn’t translate well onto a web page, so I’ll restrict myself to his 9 reasons Why Structured Content Is Increasingly Becoming A Necessity:

1. Structure formalizes content, so it can guide authors who need to make fewer decisions when writing it. It also guides readers who can find more easily where the relevant information is in the whole documentation structure or within a topic. And it guides computers which can extract relevant information automatically and reliably.
2. Structure enhances usability by creating patterns that are easy to recognize and easy to navigate with confidence.
3. Structure enables automatic delivery and syndication of content, for example, via twitter – and you’ll be surprised occasionally when and how other people syndicate your “stuff”.
4. Structure supports single-sourcing which means you can efficiently publish content on several channels, whether it’s print or different online outputs, such as a web browser, an iPad or a smartphone.
5. Structure can automate transactions, such as money transfers, whether they are embedded in other content or content items in their own right.
6. Structure makes it easier to adapt content for localization and translation, because you can chunk content to re-use existing translations or to select parts that need not only be translated but localized to suit a local market.
7. Structure allows you to select and present content dynamically. You can decide which content to offer on the fly and automatically, depending on user context, such as time and location.
8. Structure allows you to move beyond persona-ized content. This is not a typo: Scott doesn’t really like personas. He thinks they are a poor approximation of someone who is not you which is no longer necessary. With structured content (and enough information about your users) you can personalize your content to suit them better than personas ever let you.
9. Structure makes it much easier to filter and reuse content to suit particular variants, situations and users.