Category: Trends

Scrum and the Single Writer

WritesUA features an article by Kathee Kuvinka on working as a lone technical writer in an agile environment. Check it out.

More…

Sarah O’Keefe Answers Your Questions About her Intercom Article

With the theme “The Lone Advantage: What Big Teams Can Learn from Small Shops”, the December 2009 issue of Intercom featured three articles by, for, and about lone writers. One of these articles, by Sarah O’Keefe, described XML solutions for lone writers. Sarah noted that although XML has traditionally been used by large documentation teams, it can also be used by lone writers with tighter budgets and implementation constraints. Sarah went on to describe a possible roadmap lone writers could adopt to implement XML in their workplaces. This was an invaluable article for any lone writer considering moving to XML.

Sarah answered STC members’ questions about her article in a special post on STC’s Notebook. Check it out!

More…

Contemplating Help

I’ve been working on a fairly major help project over the past few weeks. In the process, I’ve been thinking a lot about how we, as tech writers, write help and what users need from help.

I was first introduced to help authoring 12 years ago while completing my degree in technical writing. Like most tech writers, I learned about books, topics, indexes, keywords, and the other components of help files. I also learned the best practices of help authoring, including breaking information into small, self-contained chunks, keeping information types separate, and focusing on user tasks rather than software features. Although HTML-based authoring tools and outputs were available at the time, publishing help on the web was still a novel idea.

After graduating, I began creating help systems in the real world. Often, this meant porting the content from a product’s printed user guide to an online platform (HTML Help, HTML, PDF, etc.) with few, if any, structural changes. This was my primary work flow for many years. And I suspect it was the primary work flow of other tech writers as well.

While we worked on user guides and help, our users’ world changed dramatically. Internet access became nearly ubiquitous in the developed world. Google made searching the web faster and easier. Blogs, wikis, and YouTube made user-generated content a reality.

What does this all mean for help? Is it even relevant in a world where users can simply search the web for thousands of free resources when they have a question or encounter a problem with their software products? I think help can still be relevant. In fact, it needs to be relevant to engage our users and allow them to fully realize the value of their tools and technology. But this requires us, as tech writers, to move beyond the basic lessons that I learned in college over a decade ago:

• As Jakob Nielsen and others remind us, web users will simply move on to the next website if they can’t find the information they need. Web users are also help users. Therefore, more than ever, we need to ensure help is task-oriented and easy to navigate.
• Simply porting content from user guides is no longer satisfactory. We need to create and structure content for help. This doesn’t mean that we can’t use single sourcing tools to create both types of deliverables, but we need to use these tools more wisely.
• We need to move help content online and ensure it’s accessible to search engines and social bookmarking tools. That said, we need to provide at least some help offline as well for times and places where web access isn’t available.
• We need to engage our users, even allowing them to contribute to content where appropriate.
• We need to keep content current, responding to any trends we see in support calls, user forums, etc.
• In the spirit of the web, we need to think of help as part of a network of user assistance tools that includes Knowledge Bases, learning management systems, user forums, wikis, and so on. Help can even be a portal to these other resources, connecting users to information they may not have even know was available online.

Many of you are already following these practices. Please share your experiences with us.

More…

It’s the Eighties All Over Again: Help Strategies for Touch-Enabled Devices

Twenty-five years ago, Apple introduced the first Macintosh computer to the world. The two main features of the Mac were the graphical user interface and the mouse. While Apple didn’t invent these technologies, it was the first company to combine them in what we would now call an integrated user experience. During the remainder of the 1980s and the first half of the 1990s, other companies followed Apple’s lead.

Today it’s hard to imagine a personal computer without a mouse or similar pointing device. However, there was a period of time when developers—and tech writers—couldn’t safely assume their users would have access to a mouse or would know how to use it.

We are beginning to enter a similar period of time for touch-enabled devices. (See my last post for an introduction to these devices.) Though touch-enabled devices are becoming more prevalent, they are far from ubiquitous.

To help you write documentation for touch-enabled devices, I’ve compiled the following list of strategies. Most of these strategies work for both touch-based interaction and more traditional mouse-and-keyboard interaction.

• If your product utilizes gestures or other complex interactions, include videos or still photos of these interactions in an introductory section of your help or manual.
• If your product works with both touch and mouse-and-keyboard interfaces, describe how to complete basic tasks with both interfaces (for example, zooming or right-clicking).
• Choose your verbs carefully. “Press” is a good alternative to “click” and works for both touch and mouse-and-keyboard interfaces.
• Ensure buttons and links in help are large enough for users to press with their fingers. If possible, prototype the help on the touch-enabled device itself.
• Make your help and other online documentation as easy as possible to navigate without a keyboard. For example, include an index of keywords that users can scroll through in addition to a text-driven search feature.
• While the tri-pane help window has become a standard, you may need to forgo it for touch-enabled devices such as smart phones with limited screen real estate.
• If you use tool tips or other embedded help features that require hovering, develop alternative techniques for touch-enabled devices.
• Image maps can be very effective with touch-enabled interfaces and are an interesting alternative to TOCs for help navigation. For example, you could include a process diagram on the help’s home page and allow users to drill down to a specific step in the process to view the relevant help topic.
• If you have access to development resources, consider incorporating touch features in your help and other online documentation. For example, you could allow users to annotate help topics in their own handwriting or navigate the help system using the same set of gestures that are available in the application. (Tip: Some of the annotation features in Adobe Acrobat and Reader work well with touch-enabled interfaces.)

Can you think of any additional strategies?

More…

Touch-Enabled Interfaces: New Possibilities for Users and Help Authors

James Bond movies are showcases for cutting edge devices—from the seemingly plausible to the slightly absurd.

In the latest movie, Quantum of Solace, an MI6 agent shows 007 and M the links between a group of bad guys on a digital table simply by touching its surface. This particular device is much closer to reality than you might think. Touch-enabled devices are becoming increasingly commonplace in schools and places of business. As our users are introduced to this new technology we, as tech writers, need to become familiar with it and how it impacts the help and others deliverables that we create.

What are Touch-Enabled Devices?

Touch-enabled devices are electronic devices with touch-sensitive displays. You interact with these devices by touching the display with your finger or a stylus, rather than using a keyboard, mouse or trackball.

While the most common touch-enabled devices today are PDAs and smart phones (particularly Apple’s iPhone), a variety of high tech companies are integrating touch-sensitive displays into desktop computers and similarly sized consoles, boards, tables, and walls. As an example, the company I work for, SMART Technologies, produces interactive whiteboards, public displays, tables, and other devices. Its flagship product, the SMART Board interactive whiteboard, is used in schools and businesses around the world.

Different touch-enabled devices use different technologies to detect touch. Some can detect your finger, a pen, or any other object, while others require a special stylus. Some devices include software that can recognize handwriting, allowing users to write notes and then capture them digitally.
While most touch-enabled devices can only detect a single touch at a time, newer devices can detect multiple touches. As a result, these newer devices can interpret gestures and, in some cases, allow input from multiple users.

Possibilities for Users

From a technical perspective, touch-enabled devices represent a simple evolution of the graphical user interfaces (GUIs) that we’ve become accustomed to over the past 20 years. Instead of typing with a keyboard or clicking with a mouse, we can now touch a screen to interact with our computers and other electronic devices.

However, touch-enabled devices also represent a significant change in how we interact with the digital world. Educators are using touch-enabled devices, such as the SMART Board interactive whiteboard, to teach to all learning types—visual, auditory, and kinesthetic. Businesses are using similar technologies to improve employee communication and collaboration. As an example, employees can now record notes on an electronic whiteboard and then save them to a file for later reference rather than having to write them on a traditional whiteboard with the obligatory “PLO” while searching for a scratchpad or laptop computer to capture them.

Multi-touch technology expands on these possibilities further by allowing multiple users to interact with a single device at the same time. Computing no longer has to be a solitary activity.

As the software for touch-enabled devices evolves, interactions in the digital world will begin to resemble those of the real world. Imagine shuffling through the photos on your computer like the ones in your shoebox, or laying out a page on a digital table like tech writers of a certain vintage used to do on drafting tables.

Possibilities for Help Authors

So what does this mean for help authors? Do touch-enabled devices radically change our job descriptions, or is it business as usual?
Currently, the help authors most affected by touch-enabled devices are those working for the companies producing the devices. We’ve needed to expand the traditional software documentation vocabulary to include terms like “press” or “touch” (versus “click”) and show users how to interact with our company’s products. In addition, we’ve had to incorporate more graphical, touch-friendly elements into our help.

Companies that produce touch-enabled devices are creating third-party developer communities with the ultimate goal of fostering broad bases of content and applications for their devices. In addition, the next version of the Windows operating system—Windows 7—will include multi-touch functionality, vastly expanding the software ecosystem for touch-enabled devices. New content and application will require documentation. You may be one of the tech writers that produce this documentation.

In the next few years, we may see more sessions at the Technical Communication Summit and other conferences, more articles in Intercom and Technical Communication, and more discussion on tech writing email lists about documentation for touch-enabled devices. A set of conventions and a body of knowledge will emerge as a result.

In the longer term, help authoring tools and platforms may offer unique features for touch-enabled devices. For example:

• Gestures for invoking help
• New navigation paradigms
• Search boxes that can recognize handwriting
• Help topics that can be shuffled, pinned to windows, and annotated in the user’s handwriting like index cards

What does this mean for lone writers?

It’s not uncommon for changes in technical communication to leave behind lone writers and other writers with limited resources. Content management systems and XML are not always practical solutions for lone writers and small teams, and video and other multimedia are often outside of our budgets.

I don’t believe this has to be true for touch-enabled devices. Using a help authoring tool or HTML editor with an open-source or freeware graphics program such as Paint.NET or Inkscape, you can create simple, effective help for touch-enabled devices. I’ve found a combination of image maps and popup windows is highly effective and can be created with most help authoring tools.

In addition, most of the best practices that we’ve been following for GUI help also apply to touch-based help:

• Make your help a mile wide and 30 seconds deep (to quote Mike Hughes)
• Make help easy to invoke but not obtrusive
• Use a simple and logical information architecture (IA)

So, although touch-enabled devices may be Bond-inspired tech, we don’t need the resources of a secret agent to create help and other documentation for them.

More…

Some Organizations STILL Don’t Get It

Not too long ago, Tom Johnson opened some old wounds for me with his post about WordPress’ biggest mistake—the mistake being the dearth of good documentation for WordPress users. It’s another example of how, in 2009, there are still organizations that don’t get the value of having a technical writer on the payroll, either as a staff member or a contractor, to make their products more usable and, therefore, more attractive to users.

Tom wrote: “WordPress documentation is only getting worse. Is there not at least a 100 page manual that you can download (rather than buying a third-party book from Amazon)? Blogger has much more marketshare because it’s an easier platform. WordPress could be more competitive in the marketplace if they simply hired a full-time technical writer to—I know this is shocking—add an online help file directly inside the application.”

I started a rant in his comments section, some of which I’ll repeat here. There’s a faction out there that insists that WordPress (the one you can host on your own site) is easy to use. So—if WordPress is easy, why is there a huge cottage industry of independent geeks and pros who do nothing but set up, extend, and troubleshoot WordPress for everyone else? If it’s so easy, how come some of these people get away, repeatedly, with charging folks $400 or more just to upgrade someone else’s WordPress blog to a new version?

Because it’s NOT.

I’m technically competent. I can replace a motherboard, install a second internal hard drive, set up a wireless network, put up a Web site, even do a little JavaScript (even though I hate it). I can do most anything with good documentation to refer to. But I find standalone WordPress to be obtuse. The scads of WordPress plug-ins make it difficult to tell what you really need, at minimum, unless you want to make learning about WordPress your new hobby—which I don’t. The so-called documentation makes it worse.

Speaking as a professional technical writer, the more complicated your product, the better your documentation needs to be. Speaking as a user and a consumer, the more complicated products and technologies become, the less patience I have with lousy documentation and the organizations who push it out there. Especially when I know how many talented, creative, reliable technical writers are out there and, at the moment, are out there looking for work.

The WordPress documentation needs to be better, as does the documentation for the plug-ins. The widespread use of WordPress demands better user support—a level that can’t be obtained by volunteers who write when they have the time. It requires a dedicated effort by a dedicated staff that works together to create a uniform documentation set. And if WordPress does, indeed, now have $29 million in funding, they can darn well afford a couple of technical writers.

More…