CommunicatorSpecial supplement: the value

of technical communicationSpring 2015

Why technical communicators are a good idea

Do we still need technical communicators?

Thinking beyondthe written word

How to turn documentation into a revenue generator

Communicator Spring 2015 – Supplement

12

More devices, less timeWith today’s technology, authors and customers alike are challenged with more information and less time to consume it in. Technology itself and our products are changing much more swiftly than even as little as 7 years ago. Whether or not your customers are demanding technical documentation in mobile

format, their patience and attention span is heavily influenced by massive consumption of mobile data.

Ironically, a quaint story from our collective childhood, Alice in Wonderland, has never seemed more relevant. Like Alice, we are all traversing a swiftly changing landscape and communicating with an ever-changing cast of customers. The Cheshire Cat could be a metaphor for your customer’s attention span, as it literally fades before our eyes. And when it comes to production, we can all relate to that seminal quote, “The hurrier I go, the behinder I get.”.

Due to these new conditions, we need to do whatever possible to make our technical content more engaging, briefer, and more ‘findable’. There are ways to achieve this, even if you are still primarily publishing to PDF.

First things first: revive the inverted pyramidMost of us have good instincts as authors when it comes to placing critical information near the top of a section or subsection. But, many of us have inherited legacy documentation (often via mergers and acquisitions) and there is seldom enough time to ‘make over’ content that doesn’t fit this guideline.

Technical manuals that were written in more leisurely times (like seven-ten years ago) don’t always put ‘first things first’. Using paper or PDF and a highlighter tool, you can swiftly traverse your content and identify the

Less time, less textMaxwell Hoffmann from Adobe shares strategies for reducing content to matchdiminished attention spans.

Maxwell Hoffmann

most important points which need to be moved to a more prominent position for your readers.

Off with their heads! (Or, does this bit need to exist?)Taking the Red Queen from Alice as a role model, we can also often do some considerable trimming of our inherited content. � Is anybody still using this section? � Is this subsection absolutely essential?

� Can the user still reach their goals with this ‘nice to know’ subsection?Often, the answer is ‘no’. We might all fantasise about removing 30% of our content (just to make our lives easier). But closer examination of ageing documentation may reveal more ‘nice to know’ versus ‘need to know’ tracts of text than we would expect.

Visual clues as to where you may find ‘fat’ in legacy documentationThere are several areas in documentation where traditional formatting makes authors feel more comfortable adding more information than is needed: � Lists (especially nested lists) � Tables � Figure captions.

Each one of these categories is a container of sorts. Lists were meant to delineate a sequence of related steps or ideas. Tables are another way to visually segregate and

emphasise critical information. Figure captions are fairly self-evident in their purpose.

By definition, a list usually contains three or more items. Some authors fall into the trap of creating ‘stair step’ nested lists that become home to a lot of narrative information that is either unnecessary, or should live in a regular

paragraph. The challenge is that overly long lists can dramatically increase both page and mobile screen count. Personally, I have attempted to read tracts of traditional

The hurrier I go,the behinder I get.

Getting the message across

If a picture is worth athousand words, we don’t

want 40 words in the caption.

Figure 1. The White Rabbit running to the rabbit hole Figure 2. Alice and her sister

Communicator Spring 2015 – Supplement

13

technical documentation on my iPhone, and in some cases I felt like my thumb would fall off after more than a dozen swipes to get to the next paragraph!

By definition, table columns will ‘squeeze’ and lengthen paragraph length text. Tables are critical for visual identification and reader retention, but we need to avoid table cells with tiny text that breaks more than five line breaks.

Figure captions are less of a problem than they used to be, but we still encounter legacy documents that have lengthy captions that state the obvious. If a picture is worth a thousand words, we don’t want 40 words in the caption.

Modern authoring tools enable more engaging graphicsSince many of our consumers have strong instincts to ‘pinch to zoom’ on mobile devices, we need to leverage that desire via more engaging graphics.

One way to achieve this is via Adobe FrameMaker 12 with the importation of instructive 3D diagrams. Current versions of FrameMaker are capable of linking parts tables or individual text references to parts, views and

animations stored in CAD diagrams. When such a document is published to PDF, the user is prompted to either click on the diagram to manipulate it, or to click on highlighted text that will change the view of the diagram.

Figure 3 shows the initial view of a 3D diagram in PDF published in FrameMaker.

Figure 4 shows an ‘after’ view of the same diagram once the user has selected a link in the published PDF that will produce an ‘exploded diagram’ image.

If the user selects an individual part, in the PDF file, it will be shaded in rose colour as seen in Figure 5 .

Zoom to new levels with brief video clipsTraditional documentation often has dozens of successive, static screen captures to illustrate a simple, multi-step task. Fortunately, you can often capture this page-consuming information into one simple, five second video clip.

The video clips will work in both PDF and in all online mobile formats that FrameMaker 12 will publish to; this is illustrated in Figure 6.

You can experience the ease of working with video by creating a sample document from one of the built-in templates in FrameMaker 12. Follow these simple steps:1. File > New > Document2. Choose the lower left button Explore Standard Templates…3. Select Chapter and then Show Sample as shown in the

screen capture below4. Go to the top of page 3 and observe this sample template

as a video already imported for you as shown below.5. File > Save the document with an appropriate name

and location.

Figure 3. Initial view of 3D diagram in FrameMaker

Figure 4. An exploded diagram of Figure 3

Figure 5. The selected part is shaded

Figure 6. Five new publishing format choices in FrameMaker 12

Communicator Spring 2015 – Supplement

14 Getting the message across

6. File > Save as PDF… and use the default location and name.

7. Once the PDF file is created, double click on, traverse to page 3 and click on the video. See how your customers can quickly become engaged with a little motion and colour.

What if you have published only to paper and there is no video?Although we would like to think that all of our readers can manipulate our PDF files on their screens, somebody somewhere will have only a printed copy of your documents. FrameMaker offers a decent compromise for this audience: QR codes.

You can swiftly insert QR codes within an alternative version of a graphic. When publishing, you may use conditional text control to ‘hide’ the video only version of a graphic, and replace it with a relevant static image that contains a QR code with an embedded URL that will take the user to the video via their smart phone!

Figure 9 shows the same ‘video’ imported into a FrameMaker document as a static screen capture; the anchored frame has an inserted text frame (to obtain an insertion point) and the simple command Special > QR code was used to embed an appropriate QR code that leads to an online version of the video.

If you don’t already have FrameMaker 12 in your possession, you can download the product for a 30 day trial and discover just how simple these steps really are.

References

TechComm Central by Adobe http://blogs.adobe.com/techcomm

Carroll, Lewis (1865). Alice’s Adventures in Wonderland

Maxwell Hoffmann is Adobe’s Technical Communications Evangelist. A former product manager for FrameMaker at Frame Technology, Hoffmann also spent nearly 15 years working with multi-lingual production and XML publishing for Language Service Providers (LSPs). Maxwell works from a virtual office in Portland, Oregon, USA, where his hobby is identifying and collecting mid-Century antiques, including vintage technical documentation. E: mhoffman@adobe.com W: http://blogs.adobe.com/techcomm Tw: @maxwellhoffmann

In summary: author with your eyesEssentially, this article simply proposes a more visual approach to authoring. Just as we used to use blackboards in classrooms or white boards in meeting rooms, we need to include compelling visual elements to engage our readers and to drive our point home.

Until the day arrives that we all have nifty plastic cuffs on our arms that swiftly flatten and float in the air to provide perfect online ‘mobile display’, we must resort to our own initiative and creativity in order to more effectively publish to both PDF and paper.

Hopefully, at the end of your workday, like Alice, you can breathe a sigh of relief as you step back through the looking glass to the comfort of your ‘normal’ world. Your cat, Dinah, will be waiting for you. C

Figure 7. The Explore Standard Templates dialog in FrameMaker 12

Figure 8. An imported video provided in FrameMaker 12’s “Chapter” Template

Figure 9. A static screen capture imported instead of video, with a superimposed QR code created in FrameMaker