How to disrupt techcomm in your organization?

If you need to “disrupt” your tech comm content, I believe it’s more beneficial to integrate content across the organization than just to get tech comm to become more business-oriented or more like marketing.

The idea comes out of a worthy new collaborative project Sarah O’Keefe launched last week, Content Strategy 101: Transform Technical Content into a Business Asset. (This blog post is based on a couple of comments I’ve left on the site.)

Tech comm goes to business school

A recurring discussion is that tech comm needs to be more business-like to be justifiable in the future, not only on this blog but also elsewhere. Proponents of this view definitely have a point, if only because tech comm is often seen as a cost center and finds it hard to claim a return on investment.

I think, however, that this view is detrimental to all involved parties:

• Tech comm risks to abandon its benefits to users and quality standards in an attempt to be “more like marketing”.
• Managers may risk permanent damage to the documentation of their product without solving the bigger problem.

Breaking down all silos

The bigger problem often is that most content production is inefficient – because it occurs in parallel silos. Many companies have gotten good at making their core business more efficient. But they often neglect secondary production of content which remains inefficient and fragmented.

I’ve seen several companies where marketing, technical communications and training (to name just three areas) waste time and money. Due to inefficient, silo’ed processes, tools and objectives, they create similar, overlapping content:

• Marketing and tech comm create and maintain separate content to explain the benefits of a product.
• Tech comm and training write separate instruction procedures for manuals and training materials.

Once companies wake up to these redundancies, all content-producing units will face pressure to streamline content and make it easier to produce and reuse. This will revolutionize corporate content production and publishing.

Quo vadis, technical communicators?

I think this issue raises two questions for technical communicators.

The strategic question is:

Which kind of content disruption is more beneficial for the organisation and for customers: Folding tech comm into marketing or integrating all content with a corporate content strategy?

The answer depends on several issues, among them:

• Does your content serve the product, the company or the customer?
• Is there a business case for a corporate content strategy?

The tactical question is:

What’s the role of technical communicators in this content disruption: Are they the movers or the movees? Are they shaping the strategy or following suit?

The answer again depends on several issues:

• What is your personality, clout and position in the organization?
• Which team has the most mature content and processes to be a candidate to lead any kind of strategic change in content?

I think tech comm can lead a content strategy, especially if and when the tech comm team knows more about content than marketing or training or other content producers.

Advertisement

My webinar slides as PDF handout

If you’ve attended my webinar “Getting ahead as a lone writer”, you might be interested in the slides in PDF:

They were supposed to be made available to attendees by the STC, but apparently that hasn’t happened as I’ve just learned yesterday.

If you have any more questions about the webinar or being a lone writer, feel free to browse my previous posts or pose your questions in a comment below.

So what’s it like to present a tech comm webinar?

Presenting a webinar isn’t much different from other “public” presentations, but the format has a few quirky effects and demands of its own.

On 29 February, I had the chance to present my first webinar. As with many first-time experiences, the newness of it all felt a little weird, there were some glitches, but altogether, it went alright. I think. I hope. Because I have had virtually no feedback.

Missing feedback

And that is already the most important difference to other presentations: You have next to no idea how you’re coming across. I never knew how vital even subtle cues are for presentations before a live audience. Does the audience follow along or do I need to be faster? Or slower? Frowns can signal that a point or a  joke didn’t get across. Genernal “antsiness” means I can pick up the pace a bit. Attentive smiles or chuckles indicate that I’m connecting. A webinar offers none of that.

The best I’ve seen other, better webinar presenters do is to ask at the beginning whether attendees can hear the audio and can see the slides changing. But after that, as a presenter, you’re on your own. It feels like talking into a tin-can telephone – without knowing whether the string is still taut.

Tin can phone, from http://www.wikihow.com

Fortunately, my webinar heroine Sarah O’Keefe had alerted me to this lack of immediate feedback. So I could identify it – but that didn’t make coping with it any less bewildering.

I think I forged ahead too fast and with too much urgency in the beginning, as if constantly groping for attention. Then I reminded myself to take a long, deep breath between my major sections.

The curse of convenient isolation

I think it’s also worth keeping in mind that even a live webinar catches everyone in a different time, place and context. What makes webinars so easy and convenient to attend, turns out to be a bit of a curse. I was presenting at 7 p.m. in Germany from my kitchen. Attendees in the US caught the webinar in the late morning or around noon, at the (home) office, I’m guessing.

This means you have less of a common context on which to build a dramatic arc or a feeling of community. In this regard, a webinar feels rather like broadcasting live television.

By contrast, some of the best live presentations I’ve witnessed gathered all attendees together, took them on a transformative trip and dropped them off at a different mental place. These were communal experiences which impart knowledge and change your perspective and rouse a group to action. I don’t think I’ve ever had that feeling in a webinar. And after my own experience, I don’t think it can be done, unless participants know each other better and have some way to interact with each other.

My webinar about getting ahead as a lone writer relies mainly on information sharing, but both times when I presented it at conferences, I was delighted to know that some attendees walked away with a feeling of “I’m not alone; I can do something about this, because others could, too.” Whether my webinar was successful along these lines, I don’t know.

Your turn

If you’ve considered presenting a webinar or have done so already, I’d love to hear your expectations and experiences. Feel free to leave a comment.

Linking topics: Cross-reference or relationship table?

Choose the appropriate reference type, cross-reference or relationship table, to link between topics so you and your readers get the most from your documentation.

When you’re moving from less-than-structured documentation to topic-based writing, one of the less apparent challenges is to link your related topics to one another. You could just keep on using cross-references, but then you’d miss out on some of the benefits of topics.

Whether you write topics using a standard like DITA or a tool such as MadCap Flare, you have a new cross-reference type, relationship tables. It is important to distinguish the two types, because each serves a unique purpose.

Cross-references

A cross-reference is the link you know from Word or other document-based writing: You create a link to a heading or a bookmark, it can show the heading title, and it updates automatically if that heading (or a page number) changes.

It leads readers from a certain point or condition to another place. It tells readers:

If you want to do or know that now, go over there.

So far, so good. This kind of link works well, if you have a document with an organised sequence. Occasionally, you need to offer the reader an occasional branching into two alternative secnarios or a jump to another place.

But when you convert your content into a pile of loosely connected topics, you have much more demand and more opportunities to relate topics.

Disadvantages of cross-references

Cross-references aren’t always the best way to relate topics because they:

• Disrupt reading flow and orientation. For users, it’s fine to make the occasional choice between scenario A or B. But offering too many links will tempt many users to wonder what they’re missing at the other end. And following link after link from within one topic to the next quickly breaks the flow of tasks and leaves the user confused.
• Create a web of dependencies. With cross-references, you tie your topics to one another in a certain preferred scenario you engineer. This scenario may not suit the user’s current need. It undermines the flexible “stand-alone” independence of topics that supports multiple use cases. And it makes it harder for writers to reuse them.

So while cross-references are easily a preferred way of linking contents in document-based writing, consider carefully how they will affect your use, and the users’ benefits, of your topics.

Cross-references in topics work well in these cases:

• Link to mandatory pre-requisites or required next steps.
• Link to a series of tasks in an overview/parent topic.

In either case, the user pretty much must follow the link to achieve anything useful, so cross-references are fine. Just make sure that the link and the surrounding text are meaningful, so users can decide whether they should follow the link.

– So if cross-references are not always recommended, how else can I link between topics?

Relationship tables

A relationship table is best to indicate that certain topics as a whole are related. It tells readers:

If you’re involved with this topic, you should also be aware of those topics.

For users, links from relationship tables appear separately, usually below the actual topic text in a section of related links or “see also”, depending on how you choose to style them.

For writers, under the hood, a relationship table is a separate file that lists by type which topics are related to one another. For example, I could have a table like this:

Concept topics	Task topics	Reference topics
Income taxes	Calculate income taxes	Income tax deadlines
	File income taxes	Addresses of tax offices

This means that the topics are related as a whole. And they will remain related, even if you update one of them by adding, changing or deleting a paragraph.

This is a pretty new concept if you’re used to writing long single documents. And it might feel awkward to have references outside and removed from the linked topics.

Advantages of relationship tables

Once you wrap your head around the idea, relationship tables have several advantages:

• Keep your topic text flexible. With such a table, you don’t lock your topic into a certain scenario as a cross-reference does. A cross-reference establishes a fixed connection – which might be irrelevant or not even available for certain users or product versions. It’s much easier to drop a topic in a relationship table where it will not appear if it doesn’t exist for certain users or products.
• Keep your references complete and up-to-date. With tables, it’s much easier to oversee the complete set of links and relationships than with cross-references inside topics. If you’ve ever tried to manually update and rephrase links to a new important topic which has replaced an obsolete topic in countless places, you will appreciate a table where you can simply add or omit any one topic.

Relationship tables are not superior to cross-references. They simply serve a different purpose. I hope this post helps you to appreciate the benefits of either type and to decide when to use which. Please leave a comment to let me know if I’ve succeeded or have been wrong or unclear somehow.

For more about converting documentation to topics, see previous posts about:

• 5 steps from legacy documentation to topics
• Wrestling with ornery topics when topics don’t quite work
• Deciding if a topic should be a concept or reference

Concept or reference, what’s the difference?

The distinction between concepts and reference topics is much easier and clearer when both support strong and clear task topics.

Concept or reference?

One of the recurring difficulties when moving to structured writing and topic-based authoring is the distinction of topic types concept and reference. It’s an odd problem because the three topic types, concept, task and reference seem rather logical and clear-cut in theory.

I’ve found that the best remedy for the confusion is the motivation that lies beneath topic-based authoring: Task orientation. Think of it this way:

• Task orientation is a design strategy for your documentation
• Topic-based authoring is “only” the method to implement task orientation.

So concept topics and reference topics exist to support tasks. “The goal for users … is not to understand a concept but to complete a task.” (p. 41, DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA).

Let tasks lead the way

Much of the uncertainty whether a topic is a concept or a reference disappears, when you have strong, solid task topics in place. Topics that directly address your users and their daily tasks and help them to get their job done:

• How do I create cool espresso drinks with my new coffee machine?
• How do I clean the milk steamer?

Such tasks are the context in which the two definitions of concept and reference from the DITA 1.2 specification make sense:

• Concepts “provide conceptual information to support the performance of tasks”.
• Reference topics “provide for the separation of fact-based information from concepts and tasks”

Note that both definition recur to tasks, so task-orientation and tasks as above are at the heart of topic-based authoring.

To help readers understand the background to tasks, you can offer concepts about the kinds of espresso drinks there are and how they differ.

To support users to actually perform the tasks, you can offer reference topics with technical specifications such as required voltage and recommended water softness.

How to distinguish them?

If you’re in doubt in particular examples, maybe the table below can help you. I got some of the criteria from a Yahoo group discussion “Concept v Reference – Battle to the Death” and from a blog post on Dubious Prospects.

Concept topics	Reference topics
Are abstract ideas	Are specific settings
Explain meaning or benefit	Give facts without much explanation
Can stay when specifications change	Change with specifications
Support understanding of tasks	Support correct execution of tasks
Are read for background information	Are read for detailed information
“Why brushing your teeth is important”	“Stages of tooth decay”