I'd Rather Be Writing » cherryleaf

Some Thoughts on Technical Writing in the Cloud

Tom Johnson — Fri, 09 Dec 2011 16:55:34 +0000

Cherryleaf has an informative article about technical writing in the cloud. Ellis Pratt writes,

There are a number of reasons why a Technical Author might want to use a cloud-based application. The first reason is cost. Instead of purchasing an application, cloud-based applications are typically offered on a monthly fee basis. If you’re looking to move to a DITA authoring environment, this spreading of costs could prove an attractive alternative to the upfront costs associated with buying a DITA solution. (See Technical writing in the Cloud.)

Cherryleaf lists some other compelling reasons for moving to the cloud as well: it allows new authors to get integrated quickly, it facilitates collaborative authoring, and allows for third-party groups to log in and make minor edits.

I agree that technical writing in the cloud has major appeal. Some help authoring solutions that you install yourself require extensive implementation. It may seem like a cost savings to install and run the software yourself, but if you have to hire an expert to come on-site and install the system, and then periodically maintain it, that expense can add up.

I know that WordPress has offered a choice between the cloud or a local install. WordPress.com is a cloud-based host; in contrast, WordPress.org allows you to download the same software and install it on your own server.

The cloud solution allows you to focus on the content rather than getting wrapped up in technical problems. There’s a strong appeal in that. However, the WordPress.com solution places various limitations on what you can and can’t do. That restriction can often be a dealbreaker. For example, WordPress.com prohibits ads and restricts you to about 150 pre-selected themes. But mostly you have the same potential to write and publish content.

With technical writing, I’d like to see help authoring companies move towards similar models: offer a freely hosted solution in the cloud, but also offer a self-installation solution. Let users choose.

Now here’s the problem. Most help authoring companies charge per license and will place the entry bar at a high financial level. For example, when we looked at easyDITA, the hosted solution cost something like 60k a year. The incentive for the cloud isn’t that strong because help authoring tool vendors don’t have any other revenue model besides the fee assessed on the customer.

But what if the cloud model could function more like Gmail or WordPress.com, offering free or inexpensive solutions? The company could earn money from side benefits such as advertising and add-ons. Even if each webpage had the vendor’s company logo in the footer, that might be tolerable. After all, every Youtube video imprints itself on videos users upload. It’s the price for using their service. Instead of despising this third-party branding, most people have become immune to it. Actually, during a previous usability research session here, when a user saw the Youtube logo on a video tutorial for our software, she immediately said, “Cool!”

The company that makes this cloud model work might be a major player in the help authoring space.

Blog Sponsors

How to Avoid Extinction as a Technical Communicator

Tom Johnson — Tue, 16 Jun 2009 05:59:10 +0000

In a career development workshop at the TransAlpine Conference in Vienna, Ellis Pratt, one of the founders of Cherryleaf, argued that technical communicators may eventually become extinct if they keep using the same methods and formats to deliver information.

Although there will always be a need for people to explain technical material non-technical people, Ellis said, others may be doing it instead, through the formats users prefer. To survive, technical writers may need to morph into content strategists, managing the information in a systematic way rather than merely creating it.

Ellis started by showing a thought-provoking video from Michael Wesch called “A Vision of Students Today.” In the video, students explain why the traditional educational model is outdated and at odds with the way they learn.

Rather than reading textbooks, today students learn through text messages, virtual chats, Facebook updates, interactive media, blogs, wikis, virtual worlds, collaborative efforts, read/write behavior, forums, podcasts, videocasts, and Google searches. The old book-reading, classroom-lecture model of learning has fallen by the wayside. It’s just not how students get the answers they need.

Although students usually aren’t the target audiences of our applications, the same concept applies to software users. The long manual and online help are declining formats few want.

Ellis relayed an observation from Tony Self, a technical communicator who organizes conferences in Australia. Self says if you look at an online help file from 15 years ago, it looks about the same as a help file produced today. This stagnancy of innovation in the technical communication community is frightening.

Whereas Web technology continues to move forward with daily developments—from Web 2.0 to Bing to Google Wave to RFID technology that scans and displays information in real-time wherever you are—technical communicators are doing the equivalent of writing textbooks for people who no longer read them.

Ellis predicts that unless technical communicators make some changes, they’re not going to be around much longer. The role of teaching people how to use technology will be passed on to others delivering it in the formats the audience prefers, expects, and learns from.

But rather than postulating any kind of new media delivery of technology, such as wikifying all your content, or providing instant support through Twitter, or porting everything into Facebook, Ellis recommends that technical communicators solve a different but related problem: managing the diversity of information.

Because information is fragmented and scattered across a dozen different types of media and sources—RSS content, content management system content, training content, engineering content, support center content, user-generated content, web content, marketing content—a need is emerging for someone to manage it all.

Ellis thinks that if writers can evolve to fill more of a content strategy role, in which they manage the fragmented information, they will survive. Rather than being a “technical communicator,” their roles will more likely be content wrangler, information strategist, user-generated content editor, information assets director, and content use analyst.

Ellis said the idea of Content Strategy and the new role technical communicators must play is something he learned in part from Rahel Bailie and her Summit presentation, “The New Face of Documentation.”

My Thoughts

Ellis and Self are right about the lack of innovation among the formats for technical communication deliverables. We need to evolve. The problem is that there’s no compelling replacement for the traditional formats. A lot of good possibilities exist—wikis, blogs, interactive multimedia—but none seems to be the online help / manual killer.

Another problem is that many of the web technologies aren’t available behind the firewall, which is where much of technical communication occurs. PHP and MySQL (required for almost every Web 2.0 blog or wiki technology) are readily available online, but these open source technologies usually aren’t robust enough for large-scale companies who require MS SQL, Oracle, or other technologies. The Web 2.0 technologies available behind the firewall usually just include SharePoint 2007. You usually can’t take advantage of cool web technologies unless you’re actually on the world wide web.

Personally, I have been trending towards quick reference guides (anywhere from 1 to 8 pages) and short video tutorials (2 to 4 minutes) as my core deliverables. I also create an online help as a searchable repository of answers, but I create it with the idea that it will be searched, not necessarily navigated for information. Single sourcing the full online help to a printed manual is just another step, so I don’t omit it, but I don’t promote it much either.

Overall, I’m excited about the new DITA publishing capabilities of Flare 5, because it means you can push the content out to additional formats more easily. You can convert DITA to the Confluence Wiki format, DITA’s XHTML target to WordPress, DITA to InDesign, DITA to web pages, and other formats.

The key to solving the problem of information fragmentation is to get the content into a format that is versatile enough to be pushed to any format. If you can keep the original source in one location and just export to different formats for your audience, letting users choose based on their learning style and preferences, then you could perhaps solve some of the problems Wesch raises in his video. (The exception of course is video and multimedia, which you can’t simply output to.)

As for switching from content creators to content managers, I’m still a bit skeptical about this. Except for public, web-based, multi-author, open-source software models, I just don’t see a lot of users contributing help content to the corporate-grown applications (except for the big ones, such as Microsoft Office). Most companies want their help content to look attractive and be accurate, and few project managers believe users can and will fill that gap if you take away the technical writer.

Blog Sponsors

Cherryleaf Survey | one man writes

Tom Johnson — Tue, 27 Jan 2009 13:36:38 +0000

Cherryleaf Survey | one man writes

Blog Sponsors

Top Technical Communication News for January 2009

Tom Johnson — Mon, 12 Jan 2009 05:29:44 +0000

Download MP3 (to download, right-click and select Save Target As)
Length: 12 min.

In this podcast, I cover the top 10 technical communication news items during the past month. This is a different type of podcast than I’ve normally done. The show notes below are excerpts of what I cover, but without any commentary.

1. Techcomm toolbox

One of the most common questions heard on many forums is “What tool do you use for [purpose]?” Answers vary, of course, because everyone has their own favorites and some folks will even answer that the right tool is “the one that best meets your needs”.

Sometimes, many people will answer that you need to look at the different tools, download trial versions, and test. But where is the list of tools to choose from?

It’s here at TechComm Toolbox, your online resource for all applications, services, consultantsm, and trainers related to technical communication.

2. Emergence of STC groups on twitter

More and more STC groups are joining and participating on Twitter: stcaccess, stcchicago, stchouston, stcboston, stcintermtn. Also, Writer River now has a Twitter feed: writerriver.

3. WritersUA Salary survey and tools survey going on

The WritersUA Tools Survey is underway. The survey is designed to provide our community with a guide to the relative popularity and satisfaction of a number of tools. … The Salary Survey provides a look at the various factors that contribute to higher salaries in the software user assistance community.

4. Jing Pro Released

Jing Pro brings you simply the best-in-class experience for quick visual online conversation. Imagine everything you already know and love about Jing, then add:

* HD quality video for the web
* Direct output to YouTube
* No more branding on the end of your videos.

5. I’m a tech writer photo gallery

Technical Writers (aka Technical Authors, Content Wranglers and Documentation Managers) have an unfair image. This project aims to challenge this image, by showing technical writers in a different light. The photos below are of technical communications professionals, doing a variety of activities.If you are involved in technical writing and you’d like to be included, contact us and send us a photo, together with your name and location.

6. STC to record and make available the entire Summit

Beginning this year at the Summit in Atlanta, STC will capture the content (audio and visuals) of almost every session and make it available to attendees at no additional cost. This will increase the value of your experience tenfold. After the conference, STC will sync the audio with the presentations and make them available (by passcode) for attendees on the STC website. This will allow [you] to “attend” all those sessions [you] missed. It will also allow [you] to revisit the ones that [you] did attend and to refresh [your] memory of the fine points made by the speakers. (From Mark Clifford’s January News and Notes)

7. WordPress 2.7 released.

This may be the last time you ever have to manually upgrade WordPress again. We heard how tired you were of doing upgrades for yourself and your friends, so now WordPress includes a built-in upgrade that will automatically notify you of new releases, and when you’re ready it will download them, install them, and upgrade your blog with a single click. [Also, BuddyPress is in beta: "BuddyPress is a set of WordPress MU specific plugins, each plugin adding a distinct new feature. BuddyPress contains all the features you’d expect from WordPress but aims to let members socially interact."]

8. Alltop publishes Tech Writing category

Alltop is an “online magazine rack” of popular topics. We update the stories every hour. Pick a topic by searching, news category, or name, and we’ll deliver it to you 24 x 7. All the topics, all the time.

9. Camtasia 6 released

When recording audio and video at the same time, it’s hard to be perfect. So we’ve made it easier to fix mistakes. Simply decouple the audio and video tracks to edit them independently. And move audio clips between (and along) tracks to line everything up perfectly. Bottom line: fewer retakes and less time spent on editing.

10. Doc to help releases 2009 version, with ribbon-based interface

What’s new: built-in xml based editor, dynamic help control for embedding help in .net applications. xhtml converter, drag and drop linking, and abbility to import project settings.