Is it about the manual – really?

How can tech comm regain agency in times of change? Imagine management decides to completely change the tech comm deliverables of your company because – it makes sense to them somehow. For example, to replace printed user manuals by iPads, as American Airlines recently got FAA approval to do. And the sense it made to them wasn’t necessarily about usability: One of the reasons given was to save $1.2 million – in fuel for flying around heavier manuals rather than lighter iPads. – Or insert your own hypothetical change of processes, tools and deliverables…

The meaning of change

What does such a change in deliverables mean for tech comm?

  • “Oh, no, another reorganization project…”
  • “Is this another shot at doing more with less?”
  • “Management has no clue how the documentation adds value to the product!”

All these reactions are legitimate, important and understandable. But they might not help us to change management’s mind, because broadly speaking we and they focus on different things:

  • We tech comm’ers focus on executing our processes and churning out good deliverables efficiently, as we should.
  • Management focuses on optimizing revenue and cash flow by changing corporate products and services, as they should.

It’s difficult to strike up a conversation if our main concern is merely a secondary factor for the other side.

It’s even more difficult if there’s not a level playing field, because we are the “change managees”, the object of change management – which is not always a pleasant experience.

So how can we regain agency in such times of change without looking like the luddite who wants to keep fiddling with layout and page breaks?

Adding tech comm meaning to change

The first important challenge is to find the meaning that’s really meaningful to managers – and nope, page breaks aren’t it. Even manuals aren’t it, if management is willing to can them. Manuals are just one way of delivering documentation – so we tech comm’ers hang our hearts on them at our own peril.

Unless manuals are the most effective and most efficient way to satisfied, productive customers, a company shouldn’t really have them – as long as it has something else which is at least as good and cheaper.

I follow a lead by Sarah O’Keefe, Ann Rockley and others who know more about tech comm-facing managers ticks than I do: We need to talk about money, either as revenue or cost. And customer satisfaction to the extent that it is tied to money:

  • The company can lose customers (= revenue).
  • Or it may find tech support calls (= cost) go up because customers need more hand-holding to get stuff to work.
  • Or it gets sued (= cost & damaged reputation), because it fails to provide legally required documentation!

These are all good reasons to insist on good, efficient documentation which requires tech comm professionals! However, they won’t mean that manuals are necessarily the deliverables of choice.

ROI of topic-based authoring and single sourcing

Breaking down content silos brings benefits and ROI to topic-based authoring, even if you have little or no translation. I’ve cut down time to write and maintain three deliverables by 30-40% by reusing topics.

Content silos

The company I work for supplies documentation for its software solution in different formats, among them:

  • Release notes inform customers about new features and enhancements in new versions.
  • User manuals describe individual modules of the product, how to set them up, how to operate them and what kind of results to expect from them.
  • Online help focuses on reference information for windows and fields, but has some overlaps with information in user manuals.

Content silos maintain separate contents per deliverable.Originally, these three deliverables were created and maintained in separate “content silos”, using separate tools and separate source repositories. So the documentation process looked like this:

  1. Write release notes in Word.
  2. Update or write user manuals in Word.
  3. Update the online help in a custom-built help tool that uses Word as an editor and Microsoft’s HTML Help Workshop to publish to Microsoft Compiled HTML Help (.CHM).

I’ve found that I could save some time by writing the release notes with the other deliverables in mind, so I could copy and paste content and reuse it elsewhere. For example, my release notes describe a new batch job which helps to automate a tedious workflow. If I describe the batch job in detail, the same content fits easily into the user manual. (Yes, it bloats the release notes, but at least the information is available at the release date, while we didn’t always manage to update the user manual in time.)

Copying and pasting worked even better once I structured the content in each of the three silos as topics. For example, a task topic from the release notes would fit almost gracefully among similar task topics in en existing manual.

But such manual copy-and-paste reuse is really not efficient or maintainable, because my stuff is still all over the place. I may write in – or copy to – four places, but then remember to update only two of them; enter inconsistency and its twin brother unreliability.

Getting real about reuse

To get the full benefits and ROI of topic-based authoring, we’ve found it’s not enough to simply write topics and keep your concepts separate from your tasks. We’ve had to adjust our documentation architecture, our tools and our process.

The guiding principle is: “Write once, publish many”. This tech comm mantra proved to be the key. We now aim to have each piece of information in only one topic. That unique topic is the place we update when the information changes. And that’s the topic we link to whenever a context requires that information.

Single sourcing is the best way to get a collection of unique topics into user manuals and online help. So we needed to consolidate our separate content silos into a single repository from which we can publish all our deliverables.

MadCap Flare is the tool we chose. It gives us a reliable, yet flexible way to maintain a common repository of topics. For each deliverable, such as release notes and user manuals in PDF and online web help, we simply create a new table of contents (TOC) which collects all topics that go into the deliverable.

With topic reuse, we define tables of contents to assemble topics per deliverable.

The writing process has changed considerably: Previously, I would focus on writing a release note entry or a chapter in a user manual. Now I find myself focusing on a specific task or concept and how to describe it as stand-alone content so it works for the user, whether it appears in a user manual or in the release notes.

The flexibilities of MadCap Flare’s conditions feature and of our DITA-based information model help us to accommodate the differences of our deliverables. We still write a few topics explicitly for a specific deliverable. For example, in release notes, short “glue” topics serve to introduce new concept topics and task topics to establish some context for the user and explain why a new feature is “cool”. In user manuals, an introductory chapter with a few topics explains what to find where and which sections to read for a quick start.

But most of the topics can now be used in release notes, user manuals and online help alike. Since I’ve gone from copy-and-paste in three content silos to single sourcing topics in Flare, the time to write and update documentation for my module has decreased by 30-40%. It’s on the lower end if a new version brings a lot of brand-new features. It’s higher if there are more enhancements of existing functionality.

tekom Danmark is off to a good start!

tekom Danmark, the Danish country group of Europe’s tech comm association, is off to a good start, thanks to good attendance and enthusiasm during the foundation event in Odense on 5 November.

Logo of tekom DenmarkThe afternoon combined official speeches with two presentations about topic-based authoring, each followed by a lively discussion. A get-together over dinner concluded the event in high spirits (and I don’t mean alcohol).

What does tekom Danmark do?

At 15:30, Per Sørensen, head of the Initiative Committee for tekom Danmark, kicked off the event that brought together around 40 technical communicators who represented a wide variety of industries and services from all across Denmark.

Michael Fritz, CEO of tekom (the German association), presented what tekom is and what it does. Denmark is not the first country group – there are already country groups in Switzerland, Italy, Romania and Turkey.

Holger Thater, a German tekom member based in Hamburg, will act as mentor to tekom Danmark. He explained specifically what tekom Danmark will be all about:

  • The general mission is what you would expect from a professional association: To provide networking opportunities, to facilitate exchange of knowledge, to offer training and qualification and to generally raise the profile of the profession.
  • To ensure that a tekom country group has a chance to succeed, it takes the explicit support of 10 tekom members in that country and a so-called initiative committee who works with tekom to found the country group and get it up and running.
  • tekom supports country groups by assigning a full-time employee who is the official liaison to tekom (Germany) and a country mentor who offers guidance and, let’s say: spiritual support.
  • tekom also offers a nascent country group an organizational framework of a start-up timeline and some budget with which to offer 4 events per year that are open to tekom country group members.
  • Interested parties are welcome to attend the events and can become a country group member for free during the first year.

After laying out the framework and procedures, Michael Fritz officially founded tekom Danmark.

Presentations and discussions

After a short break, I had the honor and pleasure to present one of the two sessions. I spoke about features and benefits of task orientation and topic-based authoring. As it turned out, aproximately half of the attendees actually use topic-based authoring, so I refocused my presentation.

Rather than going to great lengths about what topics are and how they work, I emphasised how the company I work for uses a DITA-derived information model to write topics. My presentation segued into a lively discussion about technical opportunities which our structure and our tools offer. Strategic opportunities and limitations also came up. I was glad to offer attendees a glimpse at processes and tools that work for us, and I’m happy to see that the comparison was engaging and enlightening to many.

Bo Brandt, a self-employed technical communications consultant, shared a case study where he accompanied a project from unstructured FrameMaker to Topic-based authoring with Arbortext. It was a perfect complement: His project emphasised translation more than our situation, and he had several interesting lessons and pitfalls to share. The tireless audience engaged Bo in questions about his strategy, tactics and tools.

A little before 19:00, we gathered for a group photograph, dinner and drinks. (Okay, so a little alcohol…)

What’s next?

Personally, I’m already looking forward to the next actions of tekom Danmark! Since I’m working for a Danish software company, tekom Danmark is almost like homecoming to a place I didn’t have until now. 🙂

A next event is not yet scheduled, but the idea is to move around Denmark, so look for events in København, Aalborg, Århus or the like. To keep us busy until the next event, we have already formed a tekom Danmark LinkedIn group which is moderated, but easy to join.

If you’re a technical communicator working in Denmark or if you are working with technical communicators in Denmark, I highly recommend that you join the LinkedIn group and check out tekom Danmark. It’s been great to spend an afternoon with such a diverse group of enthusiatic colleagues, and I think we’ve seen the beginning of a fruitful network!