Category: Tools of the Trade
Sarah O’Keefe Answers Your Questions About her Intercom Article
|
Ken Schatzke (Webmaster) 06 February 2010 |
Categories: | • Tools of the Trade • Trends |
| Comments: | 0 |
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!
Contemplating Help
|
Ken Schatzke (Webmaster) 20 August 2009 |
Categories: | • Tools of the Trade • Trends • Writing |
| Comments: | 0 |
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.
It’s the Eighties All Over Again: Help Strategies for Touch-Enabled Devices
|
Ken Schatzke (Webmaster) 20 March 2009 |
Categories: | • Tools of the Trade • Trends |
| Comments: | 3 |
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?
Word To Excel By Way Of HTML
|
Whitney Potsus (SIG Manager) 25 February 2009 |
Categories: | • Tools of the Trade |
| Comments: | 2 |
In my day job, I’ve been working a lot with requirements documentation and test cases. These have been huge documents for the last year—hundreds of requirements and associated test cases—that were being maintained in Word and Excel until we finally got access to the client’s requirements management (RM) system.
The Excel document was relatively easy to import into the RM system. Spreadsheets always play well with databases.
The Word document was a pain to import into the system. Word files never seem to play well with anything but Word.
After spending hours cleaning out blank lines and extra carriage returns, heavily stylizing the document, and converting a couple of hundred tables to text, the content still wouldn’t import into the RM system cleanly. It became clear that the test documentation had to be moved into Excel in order for us to get it into the RM system, but the content wasn’t going to be easy to get into a spreadsheet (either). Every heading, list item, and test step had to be in its own cell in Column C—and there was a lot going on with Columns A, B, and D as well.
With some trial and error with a couple of the Save As formats in Word, I found the solution in the least likely of formats: HTML.
By saving the Word document to the Web Page format in the Save As dialog box (NOT Web Page, Filtered or Single File Web Page), and then importing that HTML file into Excel, I had a fairly clean file conversion. To be sure, there were some blank rows that had to be deleted, columns that all had to be resized, and maybe a handful of text paragraphs that didn’t fall into the right column cell (though they were on the right row), but all in all, 4,000 rows of data fell into place rather quickly. Start to finish, the whole process took less than an hour.
Writing text—especially large quantities of it—in a spreadsheet is an adjustment. But if you’re creating text that ultimately has to be imported into a database, the time savings achieved by working from a spreadsheet are well worth the adjustment.
Touch-Enabled Interfaces: New Possibilities for Users and Help Authors
|
Ken Schatzke (Webmaster) 13 February 2009 |
Categories: | • Tools of the Trade • Trends |
| Comments: | 1 |
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.