Easiest way to add video to your tech comm

A very cheap and easy way to add video – or more honestly: almost video – to your documentation is to use animated gifs. In less formal, less complex settings, that can be totally sufficient.

For example, a translator asked us for the list of Flare topics that correspond to the table of contents. And I want to show other writers how to get such a list out of Flare. It’s a couple of clicks in the TOC editor which can easily be illustrated in an animated gif:

The gif above was created using the freeware LICECap which records screen movements and mouse-clicks. The 30-second “video” took 5 minutes to throw together, it’s 407 KB large and displays in any web browser without any codecs.

It’s certainly not the most professional way ever devised and there are no use controls whatsoever – but if you just need to illustrate a few clicks, this will let you get the job done quickly and for free!

Oh, and if you’re using Flare, you might have picked up a trick for the TOC editor along the way… 🙂

Top 6 tech comm trends for 2013

Flexibility in several dimensions is my tech comm mega-trend of the year, after mashing up the top 6 trends presented by Sarah O’Keefe and Bill Swallow in Scriptorium’s annual tech comm trends session. Head on over to Scriptorium’s site to watch a recording of the webcast and to read Sarah’s take on the trends she presented.

1. Velocity

Velocity is Sarah’s first trend which simply means that we tech comm’ers are expected to create, deliver and update content faster than before. Also gone are the days – or months – when localized documentation could be several weeks late.

If we are serious about this, we need to revamp our documentation processes. I agree with Sarah: A recent restructuring of documentation processes has sped up my throughput and made my estimations more predictable. So it has improved my productivity as a whole.

It’s also made me more flexible because my smaller task packages take less time before I finish with a deliverable. It used to take me 4 to 6 weeks to update a user manual, so interrupting this task for something more urgent was expensive because it further delayed the manual and also clogged up my pipeline. Now I take about 2 weeks for the same task which allows me greater flexibility in sequencing my tasks because I still have a chance to finish the manual by the end of the month, even if we decide that I first spend a week on something else. I could not have achieved this  flexibility without revamped processes to analyse and specify documentation and without a topic-based approach.

2. PDF is here to stay

Bill’s doesn’t see PDF go away any time soon, if only because it’s durable, controllable, reliable and downward compatible to that other durable format called print-on-paper. Google Docs might be a potential competitor, but Bill doesn’t see it making great advances on PDF in 2013.

As comments from the audience showed, there seems to be a lot of passion about the issue and some people can’t seem to wait to lay the last PDF to rest, finally. As a tech writer in semi-regulated industries, I know that I’ll be creating PDFs for my users for a looong time. It might not be a trend per se, but I agree with Bill that we haven’t seen the end of PDFs just yet.

3. Mobile requirements change technical communication

Mobile will be the big game-changer for tech comm this year, predicts Sarah. Requirements for mobile documentation mean that PDF will be one format of many – and maybe not the primary one in many cases. Other essential deliverable formats include HTML5 (for an online audience) and apps (for native or offline use).

The limited real estate of mobile devices requires more flexibility in how we structure and present documentation. Progressive disclosure can help us to integrate essential user assistance in labels or pop-ups. Beyond that, we need a strategy of what to disclose where and how to create a seamless and consistent user experience.

4. Mobile drives change

Similar to Sarah’s trend, Bill underscored the influence of mobile documentation. He emphasized the need for concise, no-frills content. Rather than jump on the progressive disclosure, Bill presented an alternative scenario: An “executive” device with the main product hooks up with a second, mobile device which presents the corresponding documentation. (I didn’t quite understand this point, I think Bill mentioned a second screen embedded in the primary device, but I’m not sure.)

5. Localization requirements increase

Bill sees the scope of localization expand as the need for translation no longer stops with external documentation. Increasingly, internal documents also need translations because corporations need to keep international teams afloat and cannot afford to lose traction due to vague or misunderstood communication.

This is also the reason why, economic advantages notwithstanding, machine translation hasn’t taken off yet. But a hybrid process seems promising in some areas where machine translations become useful and reliable after human editing. Enter flexibility as our audience now might also include far-flung colleagues – and our tasks might include editing text that’s been translated by robots.

6. Rethink content delivery

As we face diverse requirements for working at different speeds in more formats and for more diverse audiences, we need to be flexible and rethink what we deliver and how. With demands like these, pages of static contents are frequently not sufficient. Instead, users need more dynamic content and filters to customize the documentation to what they need at the moment.

Someone in the audience summed it up very well: “Think of content as a service, not a product.” To me that makes a lot of sense, because it emphasizes the recipient of that service and their situation over the static dead-on-arrival quality that comes with a tome of printed pages.

My summary

I think flexibility is a key ingredient in many of the trends Sarah and Bill discussed with the audience. The recent opportunity to reorganize how I create documentation has given me two kinds of confidence: I have a suitable process in place for now. And I can change processes and methods when I need to.

A secondary trend occurred to me as well: Thanks to Sarah’s spirited mc’ing by which she included the majority of audience questions and comments, this webcast felt a lot more communal than previous ones I have attended. It was almost like single-session, virtual mini-conference. And if industry leaders can bring us together outside of conference season, we can strengthen our networks and move our profession forwards – with just a little bit of flexibility.

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.

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.

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.

3 motivators you share with your tech comm readers

What motivates you to work most likely motivates most of your users in their jobs, too! You still need to know your audience, their tasks and background, but the good news is that you have some basic motivators in common. And these can help you understand what makes you happy at work – and what makes your users successful in their work with your documentation.

The three motivators

I take my cue from Walter Chen’s post “The science behind what motivates us to get up for work every day“. I want to focus on three motivators Chen quotes from Daniel Pink:

The 3 real reasons that motivate us to work hard every day

Pink explains … that there are in fact just 3 very simple things that drive nearly each and everyone of us to work hard:

1. Autonomy: Our desire to direct our own lives. In short: “You probably want to do something interesting, let me get out of your way!”
2. Mastery: Our urge to get better at stuff.
3. Purpose: The feeling and intention that we can make a difference in the world.

The motivators for technical communicators

Pink’s model resonated with me, and I think this is exactly what motivates me to do good tech comm work and try to get better at it:

• Autonomy for me means to find something good in the benign neglect that often meets my efforts. Of course, I have specific products, deliverables and deadlines to comply with, but our documentation team is lucky enough to be able to define its own standards and processes as long as they’re feasible.
• Mastery is the challenge to write better documentation. When I revisit obsolete documentation that I’ve written some years ago, it makes me smile: Seeing where I’m coming from and what I wouldn’t do anymore gives me a sense of progress. I’m still using task orientation and topic-based authoring – but I wouldn’t awkwardly mix concept and task in the same topic like this anymore.
• Purpose for me is my reward that my readers can be more successful or simply faster in their work if and because I’ve given them the right information at the right time.

So in a very personal, non-scientific way, I could validate these three motivators.

The motivators for documentation users

I don’t think I’m all that different from my readers in this regard. I believe they get motivated by the same things – they’re just in a different job.

So I try to keep in mind the motivators when I structure and write my documentation:

• Autonomy is tricky, of course. Someone looking up documentation has just given up the autonomy of a self-directed life and needs instruction or information. But I still try to acknowledge this and follow Pink’s advice above: “You (dear user) probably want to do something interesting (or important), let me (give you what you seek and) get out of your way!”
• Mastery is where tech comm can really excel. By presenting essential information concisely and clearly we can make it easy for our users to master their tasks and their use of our product. For this mastery, it doesn’t matter whether users learn from the documentation and internalize a skill or whether they simply know where they can look up again quickly what they don’t need to remember.
• Purpose is frequently neglected, I think. Often documentation focuses on the how, and forgets the why. But there is no sense of purpose without a why. Granted, not every topic can address the big questions of life and the universe. But as long as there is an elegant and possibly noble reason for why our product and its tasks are this particular way, it’s worth sharing it. It will give our customers an extra motivation – and make them more loyal users.

Is this what motivates you? Does it work for your readers or do they have other motivations? Please leave a comment.

Top 5 reasons I look forward to the STC12 Summit

I’ll be going to my first STC Summit in a couple of weeks and I’m already really excited about it. Here are my top 5 reasons and motivations:

1. Learn about new trends

The obvious reason to attend a conference: Many of the 80 sessions cover new industry trends – or at least topics that are new to me. We’re currently implementing a new HAT which brings a a lot of opportunities and some challenges, so I’m looking forward to:

• Andrea Ames’ Improving the User Experience by Applying Progressive Information Disclosure
• Nicky Bleiel’s Five+ Ways to Add Interactivity to Online Help
• Peter Lubbers’ Getting Started with HTML5
• Michael Priestley’s Using DITA
• Andrew Thomas and Arte Kenyon’s A Writer’s Firsthand Account of DITA in the High Tech Workplace

2. Find inspiration and solutions

The sometimes unexpected benefit: At previous conferences, I frequently got ideas about improving a broken process or solving an irritating problem, even if that was not the main focus of a session. Such insights might come from an aside comment or something I see on a slide that inspires me to connect the dots. That’s why I’m looking forward to:

• Scott Berkun’s keynote The Myths of Innovation
• Scott Abel’s Turning Technical Documentation into Profit
• Karen Mulholland’s Greatly Exceeds Expectations 
• Neil Perlin’s Developing for the Unknown
• Ellis Pratt’s What Should Technical Communicators Do When Products “Just Work”?

3. Present my own session

A highlight for will be Pattern Recognition for Technical Communicators!

I’ll be on Wednesday morning at 8:30. I know that’ll be difficult after Tuesday’s banquet and whatever after-hours may transpire. But it’s actually a very good time!

• A good time for you, because you can ease into the last day with an entertaining session that gives you a different, thought-provoking perspective on what you do anyway.
• A good time for me, because I can get a feel for the conference on Monday and Tuesday and then get it out of the way firsrt thing on Wednesday. So I hope to see you there!

The conference program

After teasing you about several interesting sessions, here’s the complete conference program:

• In a website, sortable by track, time, speaker or session code
• In PDF, sorted by day and time, with session codes and titles only
• In Excel 97-2003, sorted by day and time, with titles and main presenter

The first two are the official resources from the summit website, the spreadsheet is from me. All three are current as of May 6, but only the first one will be up to date in case of changes (an updated PDF may have a different link…). To be on the safe side, check the official summit website. – Now back to the reasons…

4. Meet old friends, make new friends

The pleasant side effect also called “networking”: As much as I enjoy social media as a virtual lifeline to stay in touch with the techcomm community, nothing beats meeting in person over a beer once or twice a year. So I’m looking forward to meeting speakers and delegates, tweeps and blog readers!

5. See Chicago

The tourist bit: I know Chicago a little bit from when I went to UW Madison in the 1990s. But I haven’t been in a while, and I’m especially looking forward to visiting the Art Institute and the new Modern Wing – or at least new to me. 🙂

6. Shop around for help authoring tools

Your bonus reason. The company I work for is not in the market right now for a new tool, but maybe you are. With more than 50 product and service providers exhibiting, you’ll have an excellent chance to see a lot of products up close and compare them closely. It’s a little like meeting friends: Nothing beats a first hands-on experience, and it’s a lot less daunting when you don’t have to install a trial version and click your way around. Vendor exhibitions at conferences were essential for us when we were choosing our tool.

7. Deep dish pizza

The gourmet reason. Thanks to Larry Kunz for the reminder, see his comment below. I was quite fond of Pizzeria Uno in my Madison days…

– If I forgot a reason to go to a conference, please share it below. If you’re attending the STC Summit, I hope to meet you in Chicago!

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.

Cheat sheets for Flare keyboard shortcuts

Harness MadCap Flare’s mighty, but daunting user interface with one of three cheat sheets of keyboard shortcuts for MadCap Flare.

We are starting to use Flare to get serious about single-sourcing and re-using our topics. I’ve been using Flare before, but I still don’t always know where to find a certain function or how to quickly open one of its many window panes. This is where keyboard shortcuts come in handy. Of course, I’m not the first user to find them helpful, so you can choose from three different cheat sheets:

The official full monty

The official shortcut reference in PDF by MadCap contains two lists of shortcuts, one sorted by tasks, the other sorted by shortcuts. The annotated tables fill a total of 14 pages. That’s good for an exhaustive reference, but less useful for a cheat sheet to keep next to the keyboard.

The quickie

This 1-page quick reference in PDF is by Scott DeLoach, a MadCap Certified Instructor for Flare who has written the MadCap Flare Certified Test Review + Developer’s Guide, MadCap Software’s Flare Training Guide, and other Flare Guides.

The new homegrown

This is my own new 2-page quick reference in PDF, mashed up from the two previous sources:

Click to download the 2-page cheat sheet in PDF.

It’s 1 page with all shortcuts listed by Flare element and 1 page with all shortcuts listed by action. If you’re using Flare, I hope you find it helpful.

My tcworld11 presentation “Getting ahead as a lone writer”

You can download the PDF slides to my presentation “Getting ahead as a lone writer” at tekom/tcworld in Wiesbaden on 19 October 2011:

My tcworld presentation "Getting ahead as a lone writer". Click to download the PDF.

For alternative formats and versions, see

• Getting ahead as a lone author, the article from ISTC’s Communicator.
• Getting ahead as a lone author, my TCUK presentation which is a little more verbose and may work better if you didn’t attend the session.

The presentation itself went very well, I think: It felt a bit strange at first to be presenting in English to what seemed to be largely a German audience. But the questions and answers session at the end showed that for many the language barrier was not a problem.

I want to thank the attentive and helpful venue staff and sound technician for their professional, attentive help! They made me feel welcome and in good hands.

Auditing Documentation and Processes at tcworld11

Auditing your documentation, and your processes, can help you to gauge estimates and issues as you prepare for localization or content migration. That’s what I learned in Kit Brown-Hoekstra’s useful 2-hour workshop at tcworld (tekom’s international half).

You can easily do the audit yourself: Take a little time, step back from your documentation, and identify weaknesses and areas for improvement. Acting on your audit results, you can

• Improve customer satisfaction
• Decrease localization costs
• Establish a baseline and a direction to develop your documentation
• Calculate costs and benefits of changes

If you don’t have an express mandate for the audit, it can be worth it to do sort of a “draft audit”. It may come out a little patchy in places, but I think it can give you a first idea of where you stand. With the initial results and measures you can more easily get the time to do an in-depth audit. (But don’t be surprised if colleagues or managers hold you to the improvements you’ve uncovered… :-))

What to audit

The organization level

Perform a strategic SWOT analysis of Strengths, Weaknesses, Opportunities and Threats of your role in your organization. Internal strengths and external opportunities (mainly) will give you useful arguments to get buy-in from management for changes and further developments you plan. Internal weaknesses and external threats (mainly) help you to assess and manage risk as you proceed.

• Strengths, for example, may include technical expertise and an understanding of user needs and tasks.
• Weaknesses, for example, are poor self-marketing or resistance to change.
• Opportunities, for example, can include agile development (which gives writers a better position in the process) and social media (if you adapt to them and moderate augmenting user-generated content).
• Threats, for example, might be smaller documentation budgets or social media (if you do not adapt or cannot keep up with user-generated ontent).

Note how threats can be turned into opportunities, if you tackle them wisely! Or vise versa…

The process level

Assess your documentation process through all stages:

Requirements > Design > Writing > Review > Edit > Localization > Publication > Feedback > Modification > Deletion

Answer the following questions:

• Are all stages well-defined?
• Is it clear when and how you get from one stage to the next?
• Do all participants in a stage know what to expect and what to deliver?
• Can you measure the success of your process?

For the sake of an efficient process, imagine each hand-over between participants or stages as an interface and try to define what’s handed over when and how as well as possible.

The product level

Identify qualities and issues of the product you document to distinguish them from those in your documentation. Weaknesses in documentation often mirror weaknesses or issues in the product, e.g., a poorly designed user interface or a workaround that’s required to complete the user workflow.

You need to know about these issues separately, because they hurt your documentation, but you usually cannot fix them yourself. You can only supply band aid.

The documentation level

Assess the structural quality of your documentation (not the quality of a manual or each topic). Answer these questions:

• Do you have a suitable information model? This is an architecure that defines the structure of your documentation on the level of deliverables (such as a manual or online help) and on module level (such as a topic or a section).
• To what extent does your documentation comply with that information model?
• Do you write documentation so the topics or sections are reusable?
• Do you reuse topics or sections to the extent that is possible?
• Do you write documentation so it is ready and easy to localize?
• Do you use standardized sentences for warnings and recurring steps to minimize localization efforts?
• Do you leave sufficient white space to accommodate for “longer” languages? For example, German and Russian require up to 30% more characters to say the same as English.

Also assess the content quality of your documentation (now look at some manuals and topics):

• Is it appropriate for your audience and their tasks?
• Is it correct, concise, comprehensible?
• Remember to audit localized documentation, too.

It’s usually enough to audit 10-20% of them to spot 80-90% of the issues.

Audit for efficiency

• Be objective. …as objective as you can, if you’re auditing your own documentation.
• Collect issues. You can use a simple spreadsheet to collect your findings: Enter the issue, its impact, its current cost, and the cost to fix it.
• Prioritize improvements. Ensure that a lower future cost makes the improvement worth doing, after you’ve added up the current cost and the cost to implement the improvement. Start with changes that cost the least and will save you the most.

Bonus tool

To really dive into quality assessment of your documentation, you can totally combine Kit’s audit process with Alice Jane Emanuel’s “Tech Author Slide Rule” which focuses on content quality. Use both and you have a good handle on your documentation – and more improvement opportunities than you can shake a stick at!

Your turn

Do you find this helpful to audit your documentation? Do you know a better way? Or do you think it’s not worth it? Feel free to leave a comment.

Join me for “Getting ahead as a lone writer” at tekom

If you’re attending the tekom conference in Wiesbaden, consider joining me for my updated presentation “Getting ahead as a lone writer” on October 19 at 8:45 a.m. in room 12C as part of tekom’s international, English-speaking tcworld conference.

tcworld conference at Wiesbaden, Germany, in October 2011

My presentation will be an updated version of the session I did at TCUK 10. I will talk about how to overcome neglect and raise your profile by running your job (more) like a business with best practices. Here’s the abstract:

Lone writers are often the only person in the company who creates and maintains documentation. They often operate without a dedicated budget or specific managerial guidance. In this presentation, Kai Weber will draw on his experience to show lone writers how to make the most of this “benign neglect”:

• How you can still develop your skills – and your career
• How you can raise your profile with management and colleagues
• How you can contribute to a corporate communication strategy
• How you can help your company to turn documentation from a cost center into an asset

Twitter meetup afterwards

Join us on Wednesday at 9:35 am on the upper floor in the foyer in front of rooms 12C and D for a #techcomm meetup after the session! @rimo1012 and I, @techwriterkai, are presenting at the same time in adjacent rooms, so if you know us from twitter, stop by and say hi!

I’ll be blogging from the conference, so watch this space…