Three types of speech balloons: speech, thought, scream.

I love to explore new ways of conveying technical information, and I’m interested in documentation as conversation. Last year I wanted to convey a “side note” on each page of a Sphinx site, as if the page were talking to you. I needed to let people know that there are additional documentation pages available. So, I went looking for a CSS design that would let me put the note into a particular tag and style as I like. I found it at Pure CSS speech bubbles. The humorous part was figuring out what speech bubbles are also called so I could do a Google search. Speech balloons? Dialog balloons? Word balloons? I never did come up with balloon but somehow found bubble.

For Sphinx sites, which are built from RST (ReStructuredText), you use a layout.html file in a _theme folder with your .rst source files. This templating is explained in more detail on the Sphinx documentation site at http://sphinx-doc.org/. In this case, the p tag is styled with css classes. Here’s what the HTML looks like:

<p class="triangle-border right"> Psst... hey. You're reading the latest content, but it's for the Block Storage project only. You can read <a href="http://docs.openstack.org"> all OpenStack docs</a> too.</p>

The CSS is much more involved, giving borders and rounded edges and putting that little triangle to indicate the speech. You can see it embedded in the Sphinx framework at tweaks.css. You can select a border color to match the rest of your page. Here’s the resulting HTML output. 

You may have seen the trend towards comic books or comics to explain technical topics, such as the one for Google Chrome at http://www.google.com/googlebooks/chrome/. There are drawn comic characters explaining the browser design considerations throughout, with speech bubbles, hand waving, folded arms, lots of body language expressed throughout. This simple side bar doesn’t attempt that level of engaging content, but it’s a playful way to let people know there’s more than a single page for OpenStack docs. What do you think about such techniques, are they playful and harmless or sloppy and annoying?

I attended several sessions on metrics, including the conference keynote, and a few key points jumped out at me:

• The wrong metrics can be worse than no metrics at all

• Metrics should be stable over time to allow for tracking

• Start by figuring out what decisions you need to make – then gather the metrics you need to make that decision

  read more

Scott Abel

By Scott Abel, The Content Wrangler

Most marketers just don’t get it. Twitter is not a fax machine. A PDF is not an eBook. Brands aren’t inherently interesting. Millions of people rely solely on smartphones to access the web. And nobody—except maybe your boss—checks your Facebook page in hopes of discovering your latest product announcement.

In just a few short years, the marketing landscape has changed dramatically—but most marketers haven’t. It’s not entirely their fault. Change is hard and humans tend to resist it. Even marketers.

Today’s consumers live in a rapidly-changing marketplace of products and ideas. They are active, digital omnivores snacking their way through a buffet of content morsels. When they need information, they seek out tasty content goodness from places where they have found it before (Google, YouTube, Facebook, Twitter, Pinterest, The Huffington Post, Forbes), often on multiple screens. And they discover new content delicacies by following the recommendations of those they know and trust.

They don’t need your help to find content of value. And, chances are, they don’t want what you’re offering, anyway.

That’s because most marketing campaigns in the digital age are little more than crusty old ideas shoved into shiny new distribution channels. What’s lacking is imagination — and a little science and mathematics. In the new world of marketing, content must become more than a channel for official messaging. Instead, content must be re-imagined and re-designed so it acts as a magnet, pulling in an always-on, socially-enabled, mobile, global world of prospects.

What’s needed is “professional-grade” content marketing.

What is Content Marketing, You Ask?

According to the folks at the aptly-named, Content Marketing Institute, “[C]ontent marketing is a marketing technique; a way of creating and distributing relevant and valuable content to attract, acquire, and engage a clearly defined and understood target audience, with the objective of driving profitable customer action.”

Simply put, content marketing is the art of communicating without selling. It’s about providing content of value, while resisting the temptation to slide into the pitch.

“Professional-grade” content marketing adds science and mathematics to the mix. To measure the success of our efforts — driving profitable customer interactions — we must be able to measure the fruits of our labors in meaningful ways. It’s not enough to count clicks, downloads, likes, friends, fans, followers and retweets. In order to be successful, we must measure what matters and be able to demonstrate (calculate) return on investment (ROI).

Deciding what to measure is critical. For instance, retailers should be measuring how much content creation costs compared to the amount of revenue it brings in. That ROI calculation is needed in order to make informed business decisions, to adapt campaigns that fail to meet expectations, and to replicate those that exceed them.

Case in Point: A Revolution in Product Documentation

One savvy company, Dozuki, saw opportunity in the do-it-yourself movement and decided to take a fresh approach to solving the problem of less-than-useful product documentation while simultaneously carving out a profitable new business model. Their efforts led to the creation of iFixit.com, a free, online community designed to help mere mortals successfully accomplish great feats of repair while simultaneously selling tools and parts.

“We’re starting a revolution in documentation,” says Kyle Wiens, CEO of iFixit.com. “Technical documentation shouldn’t be an afterthought. It shouldn’t be a dumping ground for legal disclaimers. Documentation should be vital to companies. It’s an opportunity to teach people how to do what you’re passionate about. And, if we’ve learned anything from iFixit.com, it’s that people really appreciate good instructions.”

At first, iFixit.com was little more than an online catalog of parts and tools.

“Early on, we tried to sell products, like PMU boards, without a ton of success,” says Wiens. “The need was there, but the expertise wasn’t—only those who already knew how to replace a PMU board bought one.”

Wiens and crew quickly realized that the traditional approach to marketing no longer worked. They decided to change the paradigm and to focus on publishing relevant and valuable information that drives profits.

Part online catalog, part repair university, iFixit.com was designed to attract customers by providing some of best repair guides around. They’re consistently structured, well-written, and illustrated with large, beautiful photographs. They’re optimized for mobile devices. And, they’re free. They make repairing smartphones, tablets, laptops, game consoles—even cars—seem so unbelievably easy that many people rely on the service to help them fix things on the cheap.

“When people with no repair experience are able to get their computers up and running again because they read a manual, they tend to tell people about it,” says Wiens. “We have a pretty dedicated fan base that spreads the word about iFixit’s free repair manuals.”

The approach works. Today, iFixit.com is the largest free, online repair manual on the web. The company has empowered over 15 million amateurs to fix complex electronic devices. And, they’ve sold many of their site visitors the parts and tools they need to do the job, landing the company on the Inc. 5,000 Fastest Growing Company list for the last three years. 

From a content marketing perspective, iFixit.com is a brilliant idea that marries the best aspects of community (membership, camaraderie, a sense of belonging) with technical documentation (relevant information), marketing (engaging content), social (sharing, rating, commenting) and eCommerce (sales). It allows iFixit.com to sell parts and tools at the point of need. And, it’s a perfect example of “professional-grade” content marketing done right that’s being replicated by others.

O’Reilly Media makes use of the approach in Make Magazine to teach people how to make cool DIY projects. A bicycle accessory company, Lezyne, uses the approach to teach people how to use and repair bike parts. Crucial, a computer upgrades company, uses online manuals to teach their customers how to install RAM and memory upgrades. There’s even a site dedicated to documenting veterinary surgery for e-learning purposes.

Professional-Grade Content Marketing

What makes the iFixit.com approach “professional-grade”?

First, the company understands that both the content they produce—and the experience it provides visitors—is content marketing. By re-imaging the service repair manual as a visually-rich, interactive, socially-enabled, mobile-ready marketing product, the company changed the paradigm. No longer were manuals provided as an afterthought, a necessary evil that accompanies a product purchase. Instead, they used the new-and-improved content experience to drive sales.

Second, iFixit.com knows something most firms have yet to discover. They are publishers. Sure, they exist to sell parts and tools. But, they publish compelling, valuable, accessible content in order to do so. They aren’t spraying their content all over the social web, begging for likes and praying for clicks. Instead, they create relevant content people want to share with others. And, they optimize that content for mobile devices like the iPhone, iPad, and various Android devices.

Third, iFixit.com is not just a set of free, online repair manuals, it’s an online community that encourages visitors to rate, share, monitor, and help improve their content. They empower visitors to create their own repair manuals, share stories of repair success, help one another, and gather together in groups. And, they make it easy to do so.

Fourth, by including content created by their customers, iFixit.com is optimized for search. Search engines like Google and Bing reward the site for having a robust, relevant vocabulary that includes both the official vocabulary words used by writers employed by iFixit.com, as well as the words customers choose to use.

And last, but certainly not least, the company can tie revenue directly to each piece of content they create. It’s baked into their digital DNA. Because each repair manual has its own URL, the company knows which content has earned them the most revenue and provided the highest return on investment. For instance, the company might pay $1,000 for someone to create a set of instructions designed to help consumers replace a broken iPhone screen. Because the company knows the cost of content creation, and which parts and tools were sold to people who visited the page, they know how much revenue each piece of content has earned the company. They can calculate return on investment anytime. They can prove their content is selling product.

Can you say that about your content marketing efforts? Probably not.

A New Definition of Victory

It’s time to end the content marketing “amateur hour.” Toss out your psychic-powered, old-school marketing approaches and start thinking differently about what you do and how you do it.

It’s not enough to tally up your clicks, retweets and likes and declare victory. In order to be successful in the digital age, you’re going to need to create amazing content of value and make it easy to find, retrieve, access, share and rate. And, you’ll need to collect metrics that are meaningful and use them to make actionable—defendable—business decisions.

What are you waiting for? Get busy.

Editor’s Note: Join us May 17, 2013 at 10:00AM PT for our BrightTALK webinar, Language Matters: How To Write Powerful Sentences & Paragraphs, featuring Marcia Riefer Johnston. Register today! It’s free.

Marcia Riefer Johnston

By Marcia Riefer Johnston

Many thanks to The Content Wrangler, Scott Abel, for introducing me to Guy Kawasaki’s inspiring work and for encouraging me to tell this story. —Marcia

Recently, I had an experience that any writer would give an arm for. I had my book APE’d by Guy Kawasaki.

Who’s Guy Kawasaki? When big companies want a speaker to inspire their employees, they call Guy. Guy has four million Google+ followers. Guy has, among other things, a dozen books to his credit, including the New York Times bestseller Enchantment: The Art of Changing Hearts, Minds, and Actions. When Guy’s most recent book, APE: Author, Publisher, Entrepreneur—How to Publish a Book, launched in January, it immediately shot to the top of several Amazon categories. Since then, the term “APE” has carved out a new place in the lexicon, as in “Have you APE’d your book yet?”

On March 1, Guy teamed up with social-media maven Peg “Positively Peggy” Fitzpatrick to APE my book. At least they gave me a sampling of their expert analysis. This distinguished duo spent a half hour during a Google+ Hangout on Air critiquing the social-media plan for my book, Word Up! How to Write Powerful Sentences and Paragraphs (And Everything You Build from Them).

What a learning opportunity, not to mention a thrill.

How did I come to have this opportunity? I took a cue from Guy, who likes to say, “You don’t get if you don’t ask.” I asked.

Want to see the recorded session? You’ll find the embedded video at the end of this post. The full session lasts an hour: the first half on my book, the second half on a book by fellow author Rick Watson. (If you like, jump straight to YouTube now: Video of APE Makeover Hangout with Guy Kawasaki, Peg Fitzpatrick, Marcia Riefer Johnston & Rick Watson)

Peg Fitzpatrick

Want a peek into some highlights and takeaways? Read on. Even if you don’t have a book coming out—rumor has it a few people still don’t—if you dream of writing a book, or if you use Twitter, Facebook, Google+, a blog, or any other social-media channel to sell anything, I bet you’ll find some advice here that you can use.

Guy kicked off our Hangout (after he figured out how to get his phone to stop ringing) by assessing my book title:

 “I think the title is very nice. I’m into short titles. Mine has three words. I like ‘word up.’ I think it’s a clever use. It’s like ‘man up.’ Positive energy. Like ‘Let’s get something done here.’ I like that it’s brief and upbeat and has that exclamation point. I like that, after that, you clearly explain what this book is about, there’s no vagueness. It’s plain and simple: ‘writing powerful sentences and paragraphs.’ Also—maybe this will date me—the parenthetical phrase ‘and everything you build from them’ reminds me of ‘everything you wanted to know about sex’ … I think it’s a good title and good subtitle.”

Peg: “I like it, too. It’s very descriptive. It says exactly what it is. There’s no guessing about what her book is about. If I was going to read this description on Amazon, I would know exactly what I was getting.” 

Guy Kawasaki

Whew, I thought. I got a pass on at least one thing.

Next, Guy discussed the front cover: “On Amazon, it’s going to be the size of a postage stamp. In that view, you can’t read the title.” Peg agreed: “When it’s in the thumbnail, you can’t see any of it.”

How did I never consider the thumbnail view? Action item #1: Bigger title.

On to the back cover. Guy conjured a scenario:

“That paragraph at the top seems awfully long. You have to picture people with ADHD reading these descriptions and clicking around. That’s a big eyeful … I don’t think your mindset should be someone is standing in Powell’s on a Saturday night having just had a wonderful dinner and is picking up interesting books, reading the back cover carefully, appreciating the sensibilities of the author … You’re selling to someone who has just checked in for a flight out of PDX, ripping through the security line, found out that he or she had ten minutes extra before boarding and is now standing in the bookstore inside the Portland airport, and there’s James Patterson, there’s David Baldacci, there’s Tom Clancy. Somehow this person wanders to the nonfiction section and sees Word Up! At that moment, they’re saying, ‘We’re now beginning to board.’”

Action item #2: Back cover, more scannable.

Guy noted that he didn’t love the cover design, and he cautioned against believing others who claimed they did: “Most people will not tell you what they believe … Nobody goes up to a mother who just gave birth and says, ‘Your baby’s ugly. What was your kid’s Apgar score? Because, wow!’” He suggested getting rid of the cover image in favor of an all-text cover. As an example, he cited The Chicago Manual of Style.

Deep breath. Keep the mind open. Guy is THE GUY.

We moved on to price. Guy mentioned that “APE” costs $10 for the e-book and $25 for the paperback, a $15 spread. He suggested keeping the spread no larger than that. For my eBook, I had been considering charging $2.99, which he deemed “low for a serious nonfiction book.” He added,

“There’s such a thing as communicating the branding and the positioning and the value of a book with the price. We’re charging $10 because that’s the highest we can charge and still get 70% royalty. I also believe that’s the lowest we can charge to be taken seriously. Because your book is nonfiction, and you want it to help people become better writers, it is a more serious book than a $2.99 novice-novelist-gothic-zombies-romance.”

As for the paperback price, I had proposed $21.99, which fell in the middle of the wide price range I had seen in my comparisons. Peg had done her own research and felt that $21.99 was too high. Guy noted that, when it comes to setting prices, “Nobody’s an expert. We’re all making it up.”

“Word Up” by Rob Kyff

We never resolved the question of price. The conversation took an abrupt turn when Peg pulled up the image of another book entitled “Word Up!” by a nationally syndicated columnist. Same title, same topic. “Wow,” Guy said. (Gulp.) “Books can have the identical title. They’re not trademarkable. Go look up the word ‘love’—see how many books are called ‘Love.’” But, he said, going up against an established author who has already used my main title could create confusion. “It’s not a legal problem, but arguably it’s worse than a legal problem. A legal problem you might win or lose. With a marketing problem, you’re not going to sell.”

When Peg pulled up my website, entitled How to Write Everything, Guy said, “Why don’t you just change your [book] title to ‘How to Write Everything’?”

But, but, but …

“That is a little bold,” Guy allowed. Still, if pressed to decide at that moment, now that he knew about this other Word Up!, he’d favor changing my title. For the same reason, after some hesitation, Peg agreed. A few minutes later, APE coauthor, Shawn Welch (who had participated in previous critiques but was otherwise engaged during this one), texted Peg to weigh in: he would rename the book, too.

Et tu, Shawn? Mind, open.

Next, we talked about social media. Peg had done her homework, reviewing my Twitter pages (one for me and one for the book), my Facebook pages (one for me and one for the book), my Google+ pages (one for me and one for the book), my Goodreads pages, and my YouTube channel (with book trailer pending). She asked a stunning question, “Do you feel you have too many social-media presences?”

A social-media consultant suggesting doing less?

Peg: “That’s a lot of content to manage. What you don’t want to do is repeat the exact same thing on all of those accounts.” She suggested focusing on my favorites. If she had to pick, she said, she’d go with a combination of Google+ (for the SEO value and the “great conversation”) and Twitter. As for Facebook, she said, “It’s harder. It’s your friends. They’re either going to buy your book or they’re not.”

Guy added, “I made a few mistakes trying to build social presences for specific books. At every point when I wrote a book, I thought this was going to be the last book I ever wrote. In every instance, I was wrong.” He now has a collection of book pages. He wishes that he had simply created an author page, adding, “You don’t want to build a massive fan base for a particular book.”

?!

As we talked, a small head kept popping up at the bottom of Guy’s screen. Nate climbed up into his dad’s lap, whispered hello to us, and then scooted off. Video chatting has unique joys: you get to see and hear what’s going on around people. Guy and Peg and I weren’t just talking about social media—we were using it, enjoying each other’s company.

Our conversation went on. I added a few more action items to my list. If you’re still reading this, you’ll find the whole the Hangout worth watching. I’m leaving you some things to discover.

What you won’t get from the video is what happened after Guy, Peg, Rick, and I said our Google+ good-byes. The video won’t give you any insight into the post-Hangout arguments that went on in my head. The video won’t hint at the talks I had with my husband, the messages I got from Hangout listeners, the opinions of friends, or the coaching of other consultants. (Guy’s not the only one advising me who has shepherded books to bestseller status.)

Some changes required no debate. Yes, I will make the front-cover title bigger. Yes, I will make the back cover more scannable. I will reconsider my pricing. I will follow other advice I received in this once-in-a-lifetime session with the stars. Gratefully!

But give up “Word Up”? Ditch my cover cover illustration (the blueprint sketching itself)?

I went back and forth. I slept on the whole mix of opinions. At one point, with the clarity of a tap on the shoulder, I realized that I wasn’t debating any more. The decisions had made themselves.

For one thing, I’m keeping my cover illustration. Its details may get lost at the squinty size of Amazon’s thumbnail view. And sure, not everyone will like it. But I like it, and I trust at least some of the positive response it has received. The image speaks to the playfulness of the book. I’m not writing The Chicago Manual of Style, and I don’t want to emulate its straight-text cover design.

As for my title, Word Up! stays. It has character. It has voice—the right voice. “Soul,” I’ve been told. It’s germane. It fits.

Maybe a radically different cover design and title would sell more books. Who can say? I’m okay with that possibility. During the two years of my author-publisher-entrepreneur adventure, I’ve learned two big lessons. (1) Everyone’s input has value. (2) Everyone will never agree. When you self-publish, for better or worse, you have the final word. You might as well create a book you love.

News flash: Within three days of the book’s April 27 launch date, Word Up! had climbed into Amazon’s Top 100 sales rankings in both its categories: Grammar and Writing Skills. Thanks to Guy and Peg, online shoppers now have a better chance of making out the title. For more on Word Up!, see HowToWriteEverything.com.

Before and after.
Cover design by Vinnie Kinsella. Cover illustration by Brian Hull.

Google+ Hangout on YouTube: APE Makeover Hangout with Guy Kawasaki, Peg Fitzpatrick, Marcia Riefer Johnston & Rick Watson

This is a summary of The Content Wrangler 2012 Technical Communication Industry Benchmarking Survey, an informal, web-based survey that compared responses from over 500 companies from countries around the globe. The results are not scientific, but do provide us with meaningful data points and help us spot trends.

For instance, one major trend we noticed is the adoption of structured XML content (44% of companies surveyed create XML content; 81% of those firms use DITA; 30% use custom DTDs; 16% use DocBook). The results of our research indicate that innovation is driven by complexity. The more complex the product, the more variables, the more configuration is required, the more likely advanced information development practices are in use by technical communicators and training professionals.

The Respondents

We did not attempt to capture data from the entire technical communication industry. Consultants, contractors, members of small technical documentation teams, educators, vendors, and those who did not meet our survey criteria, were allowed to complete the survey, but are not included in these results. Instead, we focused our efforts on presenting data from large, content-heavy enterprises with technical documentation and training departments. Most of these organizations employ several dozen to several hundred technical communication professionals; some employ 500 or more technical communicators. They also tend to adopt advanced information development practices that help move the field of communication forward.

The majority of survey respondents work for firms in the computer software and hardware sector (63%), followed by the financial services sector (9%), life sciences and healthcare (9%) , telecommunication (5%), publishing and media (3%) and others.

In addition to the data we share here, we contacted a sampling of the respondents for followup telephone interviews. We will share some of the stories, best practices, and lessons learned from these conversations in the near future.

A sampling of the questions…

1. What is your biggest documentation and training content challenge?

Our benchmarking survey uncovered a wide variety of challenges facing companies that produce technical documentation and training content. The biggest challenge identified was the lack of a formal content strategy.

Commonly cited symptoms of organizations lacking a content strategy include:

• Inability to effectively reuse content
• Creation of inconsistent, inaccurate, or mediocre quality content
• Producing content of unknown customer value
• Process problems and production bottlenecks

The next biggest challenges:

• Lack of governance
• Lack of time, money and resources

2. Do you utilize an agile development process to create documentation and training content?

The majority of technical documentation and training departments have not adopted an agile approach to creating and publishing content. Agile methods are based on iterative and incremental cycles that promote adaptive planning, evolutionary development, and flexible responses to change.

While 45% of companies surveyed claim to apply agile development principles to technical communication projects, few do it successfully. Typical challenges include:

• Organizational silos
• Lack of governance
• Differing approaches

The waterfall development method is still the dominant approach in use today.

3. What innovations are you planning for the future of your documentation and training content?

1. Moving to topic-based content models like the Darwin Information Typing Architecture (DITA) was the most common innovation planned for the future (21%)
2. The adoption of a component content management system was the second most common innovation planned for the future (14%)
3. Creating video documentation and training content is the third most common innovation planned for the future (11%)

4. Do you reuse documentation and training content?

85% of respondents reuse content; 5% have done so to “innovate” or “respond” to threats or opportunities quickly.

5. What are the drawbacks of content reuse?

• Writing challenges (30%)
• Upfront investment (25%)
• Governance (22%)
• Quality assurance (20%)
• Sharing conflicts (17%)
• Change management (12%)
• Difficulty finding reusable elements (11%)

6. What are the benefits of content reuse?

• Increased consistency (30%)
• Ease of maintenance and updating (25%)
• Lower total cost (24%)
• Reduce localization cost (12%)

7. Do you provide your customers with access to an online support forum or online community?

Companies are finding interesting ways to leverage the power of the crowd to help them create, update, and improve documentation and training content. 53% of companies provide customers with access to an online support forum or online community.

8. Who is responsible for monitoring your online support forum or community?

• 32% of companies rely on their customer service or technical support staff to monitor online support forums and online communities
• 20% of companies distribute responsibility across multiple roles (marketing, support, customer service, technical communication, training,and subject matter experts
• 10% of companies employ a dedicated community manager to monitor online support forums

9. Do you allow customers to edit documentation and training content?

20% of companies allow their customers to edit documentation and training content. Many of these firms use wiki-based tools that provide customers with web-based editing capability. Edits usually undergo a review and approval process, although 8% of firms allow “trusted” customers to edit and publish corrections without formal review.

10. Do you allow customers to create documentation and training content?

17% of companies today allow customers to create documentation and training content. More than one-third of those companies encourage customers to do so.

The reasons for not allowing customers to create content are usually related to concerns about:

• Quality (30%)
• Liability and regulatory compliance concerns (22%)
• Lack of management support (18%)>/li>
• Lack of proper infrastructure and/or technology (18%)

Interestingly, about 10% of companies say their customers are creating documentation and training (and publishing them online) without their approval.

11. Do you provide customers with a mechanism that allows them to rate documentation and training content?

46% of companies provide ways for customers to share feedback and/or rate their documentation and training content.

While the mechanisms put in place to help customers provide feedback about documentation and training content vary widely — from old school approaches like surveys and interviews to newer methods like blog comments and Facebook-style “likes” — organizations that use reactions from customers to improve content quality say they are looking for ways to gather immediate feedback. They’re also looking for ways to put that feedback to good use.

Companies that do it well enjoy many benefits, the most valuable include:

• Improved customer support scores (47%)
• Improved content quality (17%)
• Support call deflection (16%)
• Reduced support call volume (13%)
• Reduced average call handling time (12%)

Additional improvements include: spotting problems with product design, spotting process problems, as well as a reduction in negative feedback and complaints.

12. What mechanisms do you provide your customers to communicate with the authors of documentation and training content.

• Call center feedback (63%)
• Customer surveys (60%)
• Online forums (42%)
• Customer interviews (40%)
• Online ratings (30%)

13. What software tools do you use to create, manage and deliver documentation and training content?

Note: We asked respondents to type the names of products they use (e.g. brand name authoring tools, screen capture, video simulation software and other software tools they use to create, manage and deliver information) and did not provide them a list of tools to choose from.

As it turns out, technical communication and training departments use a wide variety of tools to get the job done. Software varies based on the type of work performed and the industry sector served. The top ten most common tools are manufactured by four companies (see list below). Adobe leads the pack with five of the top ten tools. Microsoft and TechSmith have two tools each on the list; JustSystems has one.

Adobe FrameMaker is most used?

Companies that create technical documentation are most likely to do so with the help of Adobe FrameMaker (41%). As far as authoring tools go, FrameMaker is used more than Microsoft Word (35%) and XMetaL Author (11%).

Snagit captures the second spot

?TechSmith Snagit proves to be the second most popular tool used by technical communication and training pros. 35% of companies that produce technical documentation and training have it in their tool chest.

Microsoft is still in the mix

Microsoft Word is the third most used software product. 35% of companies use Word — often along side other authoring tools. Its Office-mate and code-sharing cousin, Microsoft PowerPoint also holds a spot in the top ten with 11% of companies using the software for training and other purposes.

Adobe is the dominant force?

28% of companies surveyed use Acrobat Pro to create documentation and training deliverables, making it the fourth most commonly used tool. Adobe also holds the fifth spot with Adobe Captivate — the most often used screen recording tool (20%) — and the sixth spot with online help mainstay, Adobe RoboHelp.

The top 10

1. Adobe FrameMaker (41%)
2. TechSmith Snagit (35%)
3. Microsoft Word (35%)
4. Adobe Acrobat Professional (28%)
5. Adobe Captivate (20%)
6. Adobe RoboHelp (19%)
7. TechSmith Camtasia (12%)
8. XMetaL Author (11%)
9. Microsoft PowerPoint (11%)
10. Adobe Photoshop (11%)

The most often used content management systems

1. SDL LiveContent
2. Vasont
3. Astoria
4. BlueStream XDocs
5. RSI DocZone

A copy of The Content Wrangler Technical Communication Industry Benchmarking Survey Results Summary is included below for your convenience. Feel free to cite it, share it, use it to benchmark where your organization is compared to others.

2012 Technical Communication Industry Benchmarking Survey Summary by Scott_Abel_The_Content_Wrangler

Two weeks after the fact, I'm still processing stuff I learned at the conference. Over two and a half days with four tracks of presentations, there wasn't a single hour when I didn't want to be in at least two places at once.

I'm told there were over 350 attendees from 17 countries around the world, many of them new to DITA. The conference provided incredible depth of technical content, but will definitely need more introductory sessions or workshops next year as well to balance things out. The community is growing!

read more

An encore presentation. Bob DuCharme http://www.snee.com/bobdc.blog

Interactive eBooks leverage the latest mobile and graphic technologies to take readers beyond the printed page with captivating interactive experiences to deepen the impact of the written word. Check out the workflow involved in converting a printed book to an interactive eBook (brought to you by Aptara).

 

Aptara – Transforming Content into Knowledge

Sneaking a peek at the numbers for documentation along with the code should show us pointers about docs keeping up with code. As I suspected, there were about three major contributors to the operations manuals that span all the projects, and about three major contributors to the API docs. Also not a big surprise, I am the major contributor to both. My spidey sense felt it but I had a real gut check with the actual data.

What’s difficult about this data analysis at this time is that we still need to release the docs even while we plan for the next six months. What I really want to do is look at the past six months and all the amazing work and accomplishments we have seen. The growth has been great and the fantastic feat of the Operations Guide really topped off my year. But we are still lacking enough strong doc contributors to keep up with the pace of code growth.

First, let’s look at the OpenStack code analyzes. The last six months showed 517 contributors. For example, Object Storage grew their new contributors by over 35 people which is probably doubling the involvement. Our Infrastructure team continues to raise the bar for helping us slam in more and more bits as fast as our little cloud servers can slam them. Here’s Monty Taylor’s report:

OpenStack code patches

Essex Folsom Grizzly Patches Uploaded 11036 17986 29308 Changes Created 5137 5990 12721 Changes Landed 4235 4978 10561 Avg patches per Change 2.6 3.6 2.7 Landing Percentage 82% 83% 83%

What I want to do here is provide similar data that shows the growth of the project relative to the docs. I’m using the openstack-gitdm project to run the numbers for the documentation repos. There are eight in total but I’m just going to look at the top two, openstack-manuals and api-site. The openstack-manuals repository holds the install, configuration, adminstration, high availability, and operations guide. The api-site repository holds the building blocks for the API reference page, the API Quick Start, and other API guides (but not the API specs).

Here’s a listing of all the OpenStack doc repositories:
openstack/openstack-manuals – for operators and deployers, docs.openstack.org
openstack/api-site – for API consumers, api.openstack.org
openstack/compute-api
openstack/image-api
openstack/object-api
openstack/netconn-api
openstack/volume-api
openstack/identity-api

These are the types of statistics I want to know about doc contributions.
Number of doc contributors: 79. This is a great value.
Number of new doc contributors: 27. I like this from a growth standpoint.
Number of doc contributions: 512. There were 435 doc changes within openstack-manuals during the grizzly release, and 429 during the folsom release. Compared to over 12,000 code changes I instinctively know this wasn’t enough doc update. While we do have a good base set of docs, they are getting a bit crufty and we want to address that in the Havana release.

Number of employers: 49 (up from 37 last release). This is a high number. The highest doc contributing employer is Rackspace during the Grizzly release.

So, what about quality? The most bugs fixed by a doc contributor is 45 (well over half) by Tom Fifieldt. Tom is a great doc bug triage expert and I don’t know what we’d do without him.

How about what’s the top docs being read? The most read books are the Ubuntu Install and Deploy and the API Quick Start followed closely by the Identity 2.0 API Spec (wow that surprised me).

Here’s the reported data from openstack-gitdm. Thanks to Daniel Stangel for helping me retrieve this data. One hidden contributor is Jon Proulx, who wrote lots of the Operations Guide. Everett Toews also contributed a lot to the Operations Guide but won’t show up here. This omission leads me to suspect there may be other “ghosts” writing OpenStack docs, but I think the main point is, the top three shown below are far ahead of the fourth, fifth, and sixth-highest doc contributors.

Processed 435 csets from 79 developers 49 employers found A total of 87457 lines added, 26085 removed (delta 61372) Developers with the most changesets Tom Fifield 99 (22.8%) annegentle 86 (19.8%) Lorin Hochstein 46 (10.6%) Emilien Macchi 17 (6.0%) atul jha 11 (2.5%) Mate Lakat 10 (2.3%) Diane Fleming 9 (2.1%) dcramer 8 (1.8%) Aaron Rosen 8 (1.8%) gongysh 6 (1.4%) Ed Kern 6 (1.4%) Eduardo Patrocinio 6 (1.4%) Alvaro Lopez Garcia 5 (1.1%) Kurt Martin 4 (0.9%) Dan Wendlandt 4 (0.9%) Razique Mahroua 4 (0.9%) Gary Kotton 4 (0.9%) Dolph Mathews 4 (0.9%) Christophe Sauthier 3 (0.7%) Covers 80.459770% of changesets Developers with the most changed lines daisy-ycguo 37578 (39.9%) Diane Fleming 19381 (20.6%) annegentle 7624 (8.1%) Tom Fifield 3126 (3.3%) Lorin Hochstein 2757 (2.9%) John Griffith 2390 (2.5%) gongysh 2169 (2.3%) zhangchao010 2036 (2.2%) Mate Lakat 1927 (2.0%) Emilien Macchi 1684 (1.8%) Navneet Singh 970 (1.0%) Alvaro Lopez Garcia 647 (0.7%) Brian Rosmaita 580 (0.6%) dcramer 554 (0.6%) Dan Wendlandt 472 (0.5%) atul jha 431 (0.5%) EmilienM 428 (0.5%) Joe Topjian 411 (0.4%) Eric Windisch 376 (0.4%) Ed Kern 341 (0.4%)

At the OpenStack Summit last week I started looking for data that will help us shape the scope for the documentation for the coming release. With the right scope, we can keep up with code. Right now the docs scope that DOES release with code is docs for Python developers only, at docs.openstack.org/developers. However it seems people want install docs more than anything around release time. We will release the docs next week, 4/30/13, and have basic install docs in review now. We’ll need to keep track of doc bugs once we release of course. What we want to do in addition to decreasing scope is to increase resources, so we are working with member companies to create and fill upstream OpenStack documentation positions at each member company. Other creative ideas are welcome of course. I find this creative resourcing fascinating and I’m not about to whine about keeping up. Rather, I want to keep rising to the challenge.

Robert Glushko, Adjunct Professor at University of California, Berkeley, School of Information opened the 2013 Intelligent Content Conference on Corporate Publishing. His talk centered around a recent project he undertook — the making of an interdisciplinary textbook.

“It’s a hard project to write [an interdisciplinary text book] because it changes what a book is, a lot,” Glushko said. The solution, he discovered, “was to make it into an eBook” based on intelligent content.

Glushko takes the audience on a journey as he explores this initiative. Along the way he redefines eBooks (calling today’s definition “hopelessly inadequate”) and explains why traditional views of textbooks and eBooks don’t work and will ultimately fail. It’s not enough, Glushko says, to produce “Macbeth Multimedia — full of sound and fury, but signifying nothing”. Instead, he argues, eBooks need to be useful in new and innovative ways.

Watch the video. Then leave a comment below. We’d love to hear your thoughts on what Glushko is doing.

Mark Lewis

by Mark Lewis, Special to The Content Wrangler

Yeah, I know. The title is a pretty strong accusation, but I stand by it. The journey that led me to this conclusion began with my family at a restaurant in the Deep South. The bowl of gator chowder in front of me had been conquered. The plate full of gator ribs was my next target.

In his heavy southern accent, my son raved about his catfish dinner. I said, “Logan, if you went to the big cities far away from Florida, people would ask you the same thing they ask me, ‘WHERE ARE YOU FROM?’ ”

I thought that if Logan were to speak with someone from North of the Mason Dixon Line, they would both probably have some difficulty understanding each other. Both of them would be speaking English, but there’d be some level of challenge because of their different accents. Sure, they’d get used to each other’s after a little while and then they’d communicate just fine. But, it got me thinking.

I had recently returned from Portland where I was speaking at the LavaCon conference — whose mission is to assist organizations in solving content-related business problems that result in increased revenue and decreased production costs — so I was still super charged from brainstorming about all the presentations and the hallway conversations I had been in. In my job, I speak with a diverse group of people in a variety of roles: engineers, managers, sales people, marketing reps, quality assurance staff and executives. The problem is, we all speak English, but we don’t speak the same language.

Executives are interested in meeting corporate goals. So, their language is the language of numbers, Return on Investment (ROI), increasing revenue, reducing cost and mitigating risk. If you talk about topics outside of those areas you’ll probably see their eyes glaze over. Managers live in a world of schedules and deliverables, so their language revolves around work breakdown structures, tasks and dates. Engineers speak in algorithms. I translate that to English. Yes, I’m making fun of them, but I used to be one, so I’m allowed.

Here’s the jagged pill. Is a Chief Executive Officer or other executive going to learn your language? Doubtful. Is an engineer going to learn to speak the language of the technical writer? Unlikely. Welcome, authors, to the bottom of the food chain.

Yes, managers and others just below the CEO have to learn to speak executive just like we do, but we authors have to learn everybody’s language.

Once you’ve accepted this fact, what do you do?

You make sure that you prepare your reports and information for others in their language. One of the first steps in writing any document is “know thy audience.” Know their knowledge level, terminology and priorities.

For the executive, develop the metrics for your projects that prove how you reduce cost and help achieve corporate goals. Be the “Executive Whisperer.” If your projects have stakeholders, you’ll need to accommodate them as well. And you may have multiple stakeholders in different areas of the company. Make sure you know each of their priorities.

?

For the project manager, develop the project plans and Gantt charts that they need to integrate your project into the corporate schedule. Be the “Project Manager Whisperer.”
?
Engineers speak “flowchart” so flowcharts and swim lane diagrams are a great way to communicate with them. Be the “Engineer Whisperer.”

?

Who are you speaking with? What is their role, their terminology? What are their responsibilities and therefore their priorities? If you know what is important to them, you’ll know what information to give them. Know thy audience. Speak Southern, Northern, Executive, Engineer. In your technical writing, you make a concerted effort to write to a particular audience, so you already have this skill.

In addition to providing the right information in the right format, you must also determine what is the “right time” for information. When do they need it. The timing of news, good or bad, can be critically important. Be proactive and determine the What, When and How of their information as soon as you can. This shows commitment and helps minimize communication failures that kill a project.

Prove to others that what you are doing supports their plans and their priorities. Be multi-lingual. Succeed.

This article is part of an ongoing discussion started in the “Supporting the Business Plan” chapter of the book DITA Metrics 101. DITA Metrics 101 helps you prove the business case for intelligent content and XML. Check out the companion workbook, download a free chapter (PDF), then buy the book!
?

Social media communities, rating and review sites, wikis, blogs, eBook creation software, and other free or inexpensive web content production tools have enabled anyone with a desire (and a web browser and a decent connection to Internet) to become a publisher. But, in a world in which everyone is a publisher, how do we know what content is authoritative? How do we know what’s accurate and what’s not?

Our friends at Common Craft take a stab at answering these questions in their latest video on website evaluation. The three-minute “video explanation” examines the need for users of the web to think like editors in order to ensure the content they rely on is accurate.

We’ve all been trying to find ways to work smarter. Here at The Content Wrangler, we’ve been focusing on reducing duplicative efforts. As it turns out, we’re woefully inefficient. And that’s not a good thing for a company that specializes in helping content-heavy organizations work smarter.

Working smarter isn’t harder and it isn’t more expensive either. For as little as $20 a month, you can take advantage of one of the best time savers we’ve discovered. It’s called WittyParrot, a cloud-based, searchable, shareable repository of reusable content. WittyParrot allows you to store chunks of text, images, sounds, videos, and documents (they call these “wits”) that you frequently need to share with others. When you need a “wit”, you drag it from the palette into whatever you’re creating, be it an email message, document, Facebook post or request for proposal.

WittyParrot makes it easy for you to be productive by placing commonly repurposed content at your fingertips. You’ll save significant time not having to look for snippets of relevant content, and when teams of individuals use it together, you can ensure you’re not only communicating efficiently, but consistently.

It’s time to take content strategy seriously. In order for the discipline to move forward, we need skills. Serious skills. Skills that will enable us to solve complex content challenges without introducing a boat load of new ones. Skills that most other content professionals lack. Skills that will differentiate us from the competition.

That’s why we’ve created Content Strategy Workshops, the only event focused solely on equipping you with actionable skills you can actually use when you return to the office. Our next event takes place July 11-12 in beautiful Vancouver, BC at University of British Columbia, Robson Square. Early bird registration is open now. Discount pricing in effect until May 15. Register today! This workshop will sell out fast.

Attend our Vancouver session to learn how to:

• build a content inventory
• perform a content audit
• model and type content
• plan for translation
• develop a taxonomy
• analyze audience needs
• leverage social content
• develop an omni-channel content personalization scheme
• and more

The list of presenters is outstanding. You won’t find more experienced instructors anywhere else.

• Rahel Anne Bailie
• Branka Kosovac
• Gordon Ross
• Scott Abel
• James Romano
• Kevin Nichols
• Laura Creekmore
• Laurence Dansokho
• Paula Land
• Robert Rose
• Sarah Beckley
• Selma Zafar

What are you waiting for? Seating is extremely limited to promote learning. Register today!

Robert Rose, Chief Troublemaker at Big Blue Moose, knows a lot about content marketing. He’s spent the last few years helping organizations think strategically about how they will leverage their content to accomplish their marketing vision. In this quick take video, recorded at the Intelligent Content Conference on Corporate Publishing, Rose, spells out clearly what content marketing is (and what it’s not) and why it’s needed.

Want to learn more? Read Managing Content Marketing: The Real-World Guide For Creating Passionate Subscribers To Your Brand, by Robert Rose and Joe Pulizzi. Also of interest, The Field Guide to Content Marketing, by Robert Rose.

More and more useful. Bob DuCharme http://www.snee.com/bobdc.blog

Glad you asked! The site at http://api.openstack.org is a collection of HTML pages, and one page has an especially interesting story about how it is built. The http://api.openstack.org/api-ref.html page provides a listing of all the API calls for all OpenStack APIs that contribute docs to the page. Currently the only API that is still a work in progress is the Networking API, but here’s a patch in review and they soon will be included also.

The page has a lot of Javascript and CSS, DocBook and XSLT, XML and JSON behind it, which enables a few cool features. One is the details button, which gives an expanded set of information after you click it. Another cool feature is the ability to display either XML or JSON examples for the request or response with a drop-down list, and you can choose which to show by default. I also like the in-page search, which is more powerful than just using the browser’s page search feature because it digs deeper into the descriptions, expands to show any hits on your keywords in required and optional parameters, and in the response and requests codes. It highlights the found terms after expanding. Another cool aspect of the page is that all the Compute API samples are tested against a gate using code in the nova repository. Tested samples have been added in meticulously by Laura Alves, an awesome doc intern, with additional thanks to Sean Dague and his cohorts poking nova developers during the last dev cycle to ensure we have test samples for all API calls.

I believe there’s a lot of value in a long listing of reference information for the OpenStack APIs, and I’m glad Joe Heck took the initiative to get a blueprint going for it. David Cramer, Joe Savak, and Thu Doan at Rackspace took the blueprint and made it a reality with the Maven plugin at clouddocs-maven-plugin. The original goal of the page was to provide an all-in-one listing of all the API calls you could make against OpenStack services. At the time there were 3 or 4 services. Now we could potentially have 9 services with both admin-level API calls and end-user API calls, not to mention the extensions across 3 or 4 of the 9 services. So we are revisiting the all-in-one design of the page. Another aspect of the page is that it’s the only place to get documentation for the Compute extensions right now and the only site with tested examples without spelunking the code itself.

So, how’s it made? The basic building blocks of the page are:

• WADL files – Web Application Description Language, a proposed Wc3 standard in XML used for describing REST APIs, read all about it in the specification at http://www.w3.org/Submission/wadl/. Here’s an example with the Image API 1.0 WADL.
• XML files – Sample requests and expected responses. For Compute, these are copied right from the repository and each code submission that has an API piece must contian templates that build the example. Here’s a sample file: userdata-post-req.xml.
• JSON files – Sample requests and expected responses. Here’s a sample file: userdata-post-req.json.
• DocBook file – DocBook is an established documentation XML standard. Here it’s used as overarching XML organizing file, you can see it at api-ref.xml.

With these building blocks assembled in the openstack/api-site repository, you must also have a pom.xml to make the Maven plugin build the resulting api-ref.html page. The pom.xml is called by a Jenkins job maintained in the openstack-infra/config repository in a .yaml file. To build it yourself locally, install Maven and then do:

git clone git://github.com/openstack/api-site.git cd api-site/api-ref mvn clean generate-sources

Wait a while (maybe even 15 minutes first run) for the build to get all the dependencies it needs, then when you see BUILD SUCCESS, open the api-ref.html file in the target/dockbkx/html/ directory and revel in all the features listed above. If you want to submit a change, use the Gerrit workflow all the OpenStack projects use.

The backlog of bugs for this page is maintained at http://bugs.launchpad.net/openstack-api-site. If you see a mistake or want to ask for a addition, feel free to log a bug there. Laura Alves, our GNOME Outreach Program for Women intern, did an excellent job this past three months maintaining the page. My fellow Racker Diane Fleming is currently doing doc bug triage and fixing for the page as well. Future plans include adding a navigation layer on top of the page so it’s not one long page, but lets you pick the API for the service you’re interested in. With the additional APIs and new versions, we definitely want to keep updating the design as the APIs themselves grow and mature. Feel free to join in the API fun.

I constantly try to network locally with Austinites, and I’m meeting more tech writers with diverse backgrounds. One of Austin’s slogans is “Keep Austin Weird” and while our writers aren’t necessarily weird, their backgrounds can be!

For example, I know of one award-winning novelist in Austin who writes manuals during the day and novels at night. Did you know that Sara Gruen was a laid off Oracle tech writer who wrote “Water for Elephants” during a National Novel Writing Month? Those are cool stories of a writer’s path.

At a staff meeting a while ago, we went around the room and answered the question, “What was your first job?” I had de-tassled corn in northern Indiana when I was 14, getting it ready for hybrid fertilization by pulling the tops off of certain corn stalk rows. Another writer had worked a summer in a detention center, and another had been a bartender. Our diverse backgrounds all brought us to the same place and time and careers and meeting room.

Lately I’m seeing more and more need to hire programmers and coders who like to write and are excellent at it. This Microsoft Programming Writer I job has a great section in it:

You are comfortable creating both code and prose. You have a passion for the web and its ability to solve real world needs and create connections between people. You know that there are many technologies that fuel the web, and you’re like a kid in a candy store when you play with new APIs and discover how they expand your abilities. Your real satisfaction comes when you successfully teach someone else how to use those APIs, though, through a blog post or talking at a meetup. You’ve got a knack for coding: you use patterns and practices such as responsive design, you know your way around jQuery and Modernizr, but you prefer to code in adopted standards. In fact, you occasionally read W3C specifications for inspiration. Maybe you hope to someday edit specs…

This feels like the direction I’m moving in, and I hope you’ll come with me as I pick up blogging again. I’m interested in developers and becoming more and more like one. I’m not going after it like this “Don’t be a jerk: write documentation” post, though I do enjoy that style on others. My style is more about exploring, experimenting, trying things, and retrying.

How about you? What was your first job? Did you imagine you’d be in your here and now?

The lightweight DITA proposal for DITA 1.3 is starting to come together. The proposal responds to requirements from the community for a lightweight version of DITA to ease adoption by groups who don't need all the features of full DITA.

read more

A new radio show (and podcast) has some great observations about the future of content creation and distribution. Bob DuCharme http://www.snee.com/bobdc.blog