Adobe Technical Communication Enterprise Summit: Structured Authoring

This month, I was fortunate to attend the Adobe Tech Comm Enterprise Summit, a free conference on the latest trends in technical communication, held at the Adobe facility, in Boston, MA. It was a full and lively day, complete with informative presentations on trends in technical communication, from various thought leaders on structured authoring, including Scott Abel, CEO, from The Content Wrangler,  Inc., and Max Hoffman, from Globalization Partners International, Inc. Others presenters included Adobe’s own Kapil Verma, Ankur Jain, and Tom Aldous, followed by a detailed case-study on how to leverage Adobe’s Technical Communication Suite 3.5 , from Accenture’s Rick Thompson.

Technical Communicators, as Content Management Consultants

As described in my earlier post, Scott Abel’s keynote suggested that technical communicators are now more management consultants for content, as opposed to creators of content. Working alongside product management, Abel called upon technical communicators to continue breaking down the cylos within their respective organizations, with the objective of optimizing every part of the content delivery process. The end result, according to Abel, is re-usable content, developed for multiple delivery channels, audiences, formats, and languages.

Key Trends in Technical Communication Today

Adobe’s Kapil Verma described key trends in technical communication
today, driving the evolution of Adobe’s Technical Communication Suite 3.5:

  • Globalization, opening up new markets, in
    emerging economies
  • Multiple devices, requiring multi-screen, multi-channel
    publishing options
  • User-generated content & democratization of
    content creation
  • Increasing demand for rich media
  • Increasing demand for highly personalized content

Later that day, Thomas Aldous made a strong case that the
Adobe Tech Comm Suite, which includes both unstructured and structured
authoring versions of FrameMaker 10.0, sets technical communicators up for long-term success, as market requirements continue to evolve.

Structured Authoring: Reasons for Making the Change

Verma provided helpful guidelines, for when making the
change to structured authoring may make the most sense. Structured authoring
may be suitable for your organization, Verma advised, when you’ll be…

  • Translating doc into multiple languages
  • Transfering documentation, between systems
  • Managing dispersed content production
  • Creating and maintaining a large volume of
  • Making frequent documentation updates
  • Supporting multiple production variants
  • Publishing multiple formats
  • Following a standard documentation structure

Verma followed up these recommendation, with a meaty analysis, on how to derive the highest ROI from your migration to structured authoring.

More Information

In my next post, be on the lookout for highlights, from Ankur Jain’s presentation, on developing an enterprise social collaboration strategy.

I haven’t used the structured version of FrameMaker, or Robohelp in a few help authoring assignments, so in the comments, please feel free to add your experiences with these tools, or comparisons with other authoring tools. Past versions of FrameMaker (up thru version 9.0) have spoiled me for all other desktop publishing tools. How has making the transition to version 10.0 been for you?

And oh, before I sign off, a very Happy 25th Birthday, FrameMaker. Thanks to Adobe and all the presenters for their time and for the generous knowledge share. 

About This Blog: Copyright Information

Contacting the Author: Content for a Convergent World – Peg Mulligan’s Blog

Trends in Technical Communication: Web Content Accessibility (Part II)

Through the mobile web, overlapping best practices for web content accessibility are about to go prime time. (See Web Content Accessibility and Mobile Web: Making a Web Site Accessible Both for People with Disabilities and for Mobile Devices).

To prepare, I’ve been reacquainting myself with my treasured copy of Letting Go of the Words: Writing Web Content that Works, by Janice (Ginny) Redish. There, you’ll find in my opinion, what’s probably one of, if not the best books available, on writing online.

Tips for Writing Accessible Web Content

Throughout her book, Redish sprinkles generous tips on web content accessibility. Here are just a few:

Let people choose their own text size (p. 148). Provide buttons on the web page to remind site visitors that they can adjust the size.

Make illustrations accessible, with meaningful alt text (p. 305). To develop helpful alt text, Redish suggests following the World Wide Web Consortium’s advice, imagining that you are reading the web page aloud, over the telephone. Ask yourself: “What would you say about the image to make your listener understand it? (From

Mark headings with the proper HTML tags (p. 237). Those using screen-readers want to scan web pages, just as sighted visitors do, Redish explains. If the headings are properly tagged, your blind web users can “scan with their ears,” (p. 320), by jumping from heading to heading.

Start headings with a key word (p. 247). Those who are listening to screen-readers scan only the first few words, in each heading. Make sure to include your keywords, at the beginning.

Write meaningful links (p. 318.) Click here and More links are useless to web visitors who are listening via screen-readers. Instead, Redish suggests rewriting these links to specify what visitors will get “more” of” and to use more informative words, as the link.

Tips for Formatting Accessible Web Content

Meanwhile, the January issue of Intercom–the Magazine of the Society for Technical Communication–provides detailed tips on making your web content’s formatting more accessible.

Properly tagging web content helps blind visitors using screen-readers and other forms of assistive technology to skim your site. It also helps make your document more accessible because anyone who cannot read your document can reformat it, by importing a new template, or editing the styles in your document, until each has a format they find readable (pp. 13-14).

According to STC’s Cliff Tyllick (@clifftyll) on Twitter, here are ways to take control of your text:

  • Use heading styles.
  • Use styles—or at least automated formats—to create lists.
  • Use styles to control paragraph formatting.
  • Use styles to control special character formatting.
  • Insert tables—do not draw them.
  • Use tables to display data, never simply to position content.
  • When you use informative illustrations, position them in line with text.
  • Associate alternative text with each informative illustration.

Additional Resources

For more information on writing for the web, check out Ginny Redish’s excellent slide presentation (PDF link follows): Letting Go of the Words- Content as Conversation.

For a clearinghouse of information on web content accessibility, I also highly recommend STC’s AccessAbility SIG (@stcaccess on Twitter), by STC SIG manager Karen Mardahl (@kmdk on Twitter). In Jan.’s Intercom issue about accessibility, Karen wrote a great article on “Captioning Videos on YouTube.”

If you know of other resources, please feel free to add them to the growing list of Web Content Accessibility resources, which appeared in my last post. Thanks to folks for suggestions so far, including these resources: WebAIM: Web Accessibility in Mind, WebAxe: Podcast and Blog on Practical Web Design Accessibility Tips, and the IBM Developer Accessibility Guidelines.

I’ll make sure to add these and any other suggested resources to the final list.

Please also feel free to add your best accessibility tips, in the comments. I’m still very much learning and am grateful for your help and recommendations.

About This Blog: Copyright Information

Contacting the Author: Content for a Convergent World – Peg Mulligan’s Blog

Trends in Technical Communication: Web Content Accessibility (Part I)

In January, Intercom–the magazine for the Society for Technical Communication—provided an excellent issue on all things web content accessibility, including articles on “Accessibility 101 for Technical Writers,” “Captioning Videos on YouTube,”and an “Alternative to Universal Design in Mainstream Video Games.”

Minor Accommodations, Major Impact

The article made me recall a few contracts back, when I was working as a technical writer, in a government setting. For the first time in my fifteen-year career, due to government mandates, an accessibility check was a required part of the documentation’s production process.

At the time, I remember being surprised at how relatively painless most of the accessibility guidelines were to implement—simple changes at the markup level, including alt tags, page titles, headings, and lists, which were only time-consuming if they had to be revised globally, as opposed to correctly implementing them the first time.

For print documents, I implemented these additional accessibility guidelines: providing alt text for embedded images, making sure to include an alternative format (.txt, .doc, or .xsl) for PDFs, keeping file sizes down to less than 5 megabytes, and adding electronic titles to Microsoft Office documents.

Whether for print or online documentation, I learned the cardinal rule of accessibility: Content needs structure.

Optimizing our Process

Some of the accessibility principles were not so straightforward, especially structuring content. However, information design is part of many technical writers’ standard practice. Others were not difficult to incorporate into my writing routine, once they had been pointed out to me.

Given how much of an impact these relatively minor accommodations can make for a more accessible Web–and how a simple style sheet could remind writers to more seamlessly incorporate many accessibility best practices across their content–it seems almost impossible to me, that this government contract was one of the few times I have formally encountered best practices for web content accessibility.

Convergence: Web Content Accessibility and the Mobile Web

With the rise of the mobile web, we may finally see more mainstream settings start addressing accessibility. As it turns out, what’s good for designing for people with disabilities is also good for designing mobile content. (For more on these best practices and for resources on web content accessibility, stay on the lookout next week, for Part II of this post.)

Questions and a Call to Action

In the meantime, for technical writers especially, how much has web content accessibility been a part of your job? How does accessibility apply to user assistance and structured authoring?

And I’d like to conclude here, with a call to action mainly to myself, to do a better job incorporating alt tags for the images, in my blog posts, especially the retroactive ones, where I wasn’t following the practice. In the end, accessibility is about taking the time to do the little things–many times also the right things (both for our disabled users, and in the case of mobile content, our bottom lines)–consistently.

About This Blog: Copyright Information

Contacting the Author: Content for a Convergent World – Peg Mulligan’s Blog

Trends in Technical Communication: Mobile-Accessible Documentation

In a recent post at TheSearchAgents blog, Mary Hayes highlights the growing importance of mobile devices, which according to AdAge Global are “poised to become the most ubiquitous media device in history.” AdAge Global reports that worldwide, mobile usage far outweighs that of the PC:

PC vs. mobile penetration rates for China are (20% vs. 57%); India (4% vs. 41%); Brazil (32% vs. 86%); and Indonesia (5% vs. 66%).

By Christmas 2011, Nielsen has estimated 1 in 2 Americans will have a smartphone.

Despite these trends, blogger Chris Brogan aptly observes in his Future of Media series that “the way we create media right now is still primarily as if we’re imagining a laptop.”

Understanding Mobile Users

In the Difference Between Mobile Search and Desktop Search, Dhrub Raag explains that “users accessing the Internet via desktop PCs or laptops are in a totally different mindset from their mobile counterparts,” with PC users “spending large chunks of time in a fixed location,” possibly spending hours searching and researching.”

Mobile users, on the other hand, are on the go, with a specific task to accomplish, usually in transit.

Mobile users “snack” on the Internet in small browsing sessions, and generally access the web, when they need a quick answer.

Implications for Technical Communicators

In his recent alertbox, Mobile Content Is Twice as Difficult, Jakob Nielsen recommends that for optimal usability, “websites (and intranets) must design a separate mobile version.” (Mitch Joel explores similar themes in Do You Need a Mobile Version of Your Website?)

Extending Nielsen’s findings about mobile content to technical communication, it would make sense that we must similarly repurpose our desktop user assistance for mobile users.

QR Codes: The Future of Technical Communication?

As part of a single-sourcing solution with multiple outputs (including PDF, WebHelp, and WebHelp Mobile), help-authoring tool MadCap Flare 7.0 already offers a Mobile format.

What’s more, Madcap Flare has expanded its leadership in mobile-accessible documentation, with support for creating and publishing Quick Response (QR) codes in printed documents.

Mobile devices can scan the QR Codes to access searchable, interactive content on the Web, including product usage information (see 10 Ways to Use QR Codes).

Repurposing User Assistance for Mobile Delivery

Most importantly, repurposing desktop content means keeping in mind what Mary Hayes calls the 15 Second Rule:

Mobile users want to find, not search. Determine what you want the user to do, then ask, “Can they do it in 15 seconds?” “Chances are, if they can’t, you’ve lost them for good.”

Streamlining content for the mobile platform will not only accommodate mobile users’ most immediate task requirements, it will also mean faster page load speeds.

…but Jakob Nielsen’s findings suggest to me that repurposing content for mobile users, involves a lot more than simply developing quick reference versions of our user assistance, in a mobile format.

Instead, repurposing desktop content for the mobile web will require technical writers to think even more than we currently do today about information types (Concept, Task, and Reference),  delivering the right type of information, via the media that best support that kind of content. Level of detail and scope, as well as how our efforts complement other content disciplines will take on increasing importance.

We’ll also need to start developing mobile-accessible documentation in a high-context communication style, which contrasts to the more low-context style, which has traditionally defined technical writing deliverables, especially in the US.

Another important consideration will be incorporating links back to the web versions of our user assistance or corporate web sites, for additionl context, as well as where to embed QR codes in the user assistance, which can possibly complement broader corporate objectives, as part of a comprehensive content strategy.

Getting Started: Audience Analysis for Mobile Users

When formulating a mobile strategy, Hayes suggests considering Action, Context, Location, and Mood, as part of our user personas. Though Hayes was writing about marketing content, I believe the same questions apply to user assistance, delivered via the mobile web, or otherwise:

  • Action – what does your audience want to achieve?
  • Context – what is specific to their situation?
  • Location – where are they?
  • Mood – how are they feeling? (This point ties in especially well with Trends in Technical Communication: Affective User Assistance.)

Your Thoughts?

Has your documentation group used Madcap Flare’s WebHelp Mobile format? Do you have any additional tips on how to customize user assistance for a mobile audience? Can structured authoring achieve some of the same ends?

What ways can QR codes enhance the product documentation?

Finally, how can our collective organizations help technical communicators better understand our customers, especially the context in which they use our products? And how can technical communicators continue to learn more about their customers, on their own? (see Analyzing Audience Without Direct Access to Customers).

About This Blog: Copyright Information

Contacting the Author: Content for a Convergent World – Peg Mulligan’s Blog

Trends in Technical Communication: Exploring SEO-Friendly Authoring Tools

Another emerging trend in technical communication is making sure our documents get found on Google. Search engines are where our customers turn to first for answers, yet most frame-based topics from traditional help authoring tools aren’t crawlable by search engines.

When technical documentation is available on the web, it can be a major sales tool and revenue generator. So says MindTouch CEO, Aaron Fulkerson, in The Evolution of the User Manual:

Fulkerson reports that for some companies, documentation is bringing in over 50% of qualified leads, through organic search results. At MindTouch, 70% plus of site traffic comes from organic sources, with the documentation generating more than half of overall site traffic. More impressive, MindTouch documentation drives over half of all lead generation.

Are Traditional Help Authoring Tools Holding Us Back?

In Search Engine Optimizing Your Help Content for Google, Tom Johnson provides an excellent analysis on the limitation of most frame-based help authoring tools, in making our content available on the web. He raises the question of whether we should abandon these tools:

As the importance of visibility on Google grows, and as companies recognize and treat their help content as an SEO asset for the online visibility and ranking (not to mention marketing) of their products, shouldn’t we put our help content on web-friendly platforms that will maximize their visibility in Google’s search engine results? Are traditional help authoring tools holding us back from realizing the SEO power of our help content?

Workaround for Frame-based Help

In the comments of Johnson’s post, Tony Chung suggests an interesting workaround for getting Frame-based help on the web. The proposed workaround would not, however, solve the problem of people linking directly to the help content because “for the most part, the location bar only displays the URL of the master frame and not the topic within it.”

Considering Alternative Tools

In the post Experiences with Reader Comments on the Atlassian Documentation Wiki,  Sarah Maddox shows how incorporating user-generated content into a documentation wiki helps drive more traffic for her company, than the general web site. She discusses the importance of Google Analytics in measuring site stats, and in a follow-up post, she explains how she balances customer edits and documents, against other priorities (including ensuring the most sensitive documents remain accurate).

Help Docs as Community Hub

Returning to Mindtouch as an example, the Gilbane Group has written a case study, Managing Content for Continuous Learning at Autodesk: When DITA Flows into a Social Web Platform, showing how Autodesk has created a customer-centric community experience, around their help docs.

Your Take?

How important is it for our help topics to appear in search results? What do you think about Tom Johnson’s question: “Are traditional help authoring tools holding us back?” Are alternatives like Confluence and MindTouch, the future of technical communication? How do these approaches fit in with a more structured approach to documentation?

Finally, can the help docs not only help drive sales but also help reinforce our customer community? Would this model help unify communications across the various content disciplines?

About This Blog: Copyright Information

Contacting the Author: Content for a Convergent World – Peg Mulligan’s Blog