Marketing and Tech Writers

In a recent post on his blog, Neil Perlin noted that business and financial knowledge is critical to the success of tech writers. This is particularly true for tech writers working by themselves or in small teams who need to justify the hiring of new writers or the purchase of new software.

Marketing is an area of business that many tech writers, myself included, don’t fully understand or appreciate. That’s why I found this video of Seth Godin from the 2008 Business of Software conference interesting. While Godin’s talk is geared towards software developers, it has implications for tech writers as well.

More…

Free Teleclasses In The Upcoming Weeks

A long-time acquaintance of mine, Curt Rosengren, just wrote to tell me that he’s offering a couple of free one-hour teleclasses in the coming two weeks.

• June 24 – How to make hiring YOU a no-brainer!
• July 1 – Get Wild About Work and make passion your competitive advantage

If you’ve not yet heard of Curt, or heard me talk about him, he’s a self-admitted Professional Malcontent turned Passion Catalyst, having pulled himself out of an unfulfilling corporate career and planted himself into a new life path that re-introduced passion, and near-euphoria, into his professional and personal lives. Through his Passion Catalyst coaching business, he’s helped countless others find their own ways out of malcontent. I discovered him through his original blog, Occupational Adventure, and have continued to follow him through his newest blog, the M.A.P. Maker. M.A.P. Maker is a self-required daily read for me, and I continue to trawl his Occupational Adventure archives and share the gems I find with friends and colleagues.

If you find yourself caught in a period of personal or professional frustration, suffocation, or desperation, time with Curt in one of his classes or in one-on-one sessions invariably helps people start reconnecting with their dreams and with themselves.

Whether you attend the teleclasses or not, I encourage you to also check out his books:

• The Occupational Adventure Guide (ebook)
• 101 Ways to Get Wild about Work (paperback or ebook)

If you get the latter book, be careful about bringing it to work as co-workers will quickly develop the habit of helping themselves to your copy.

More…

Well, This Is What We’ve Been Saying For Years

TechRepublic recently posted an article titled, 10 ways developers can meet user expectations and ease frustrations. The list included things like accurate data, responsive user interfaces, compatibility, responsible resource consumption, and others. Being a technical writer, #7—Documentation, naturally caught my attention:

We all know how much developers dislike writing documentation. So we tell ourselves that the application is so easy to use, “only an idiot would need a manual.” There are two problems with this thinking. The first is that the world has plenty of idiots in it. The second is that we are usually wrong about how easy the application is to use. If your organization has a technical writer to create the documentation, involve that person from the get-go; the top complaint I hear from technical writers is that they are handed a nearly finished product and told to document it, with little insight into how it actually should be used. If you do not have a technical writer available, you will really need to work hard to make sure that the documentation does not merely state the obvious and is written in a way that will be helpful to end users who are unfamiliar with your application.

I’ve been at this for more than a decade and it mystifies me that this point STILL has to be drummed into the heads of managers and development teams. Or that #10 on TechRepublic’s list—Does what it says it will—has to be either. With all the blogs out there that crucify products that are anything but user-friendly, and with help desk call databases documenting the “how do I….?” calls that come in over and over again, it shouldn’t be such an epiphany that users have no patience for products that

• don’t deliver on the promises made during sales pitches
• are not intuitive to use
• don’t have even the the most basic of documentation

So, instead of burying this discussion on our SIG listserv or the Discussion Board of our LinkedIn Group, let’s get it out in the open for everyone to read. What’s the reason—or reasons—for this persistent block? What’s the “magical sales pitch” that you, fellow tech writers, think will help clear the blocks once and for all?

More…

Contemplating Natural Talent

While catching up on some reading in my RSS aggregator, I discovered a post that Tom Johnson wrote about Malcolm Gladwell’s book, “Outliers.” About an hour later, while looking at Seth Godin’s blog feed, I discovered he’d responded to Gladwell’s book back in December.

Reading both of them, and having a strong reaction to both, prompted me to pull “Outliers” out of the middle of my to-read stack and read it. In arguing that natural talent isn’t much more than a myth, Gladwell states that:

  * Your success is greatly determined by where and when you were born.
  * Superstardom is achieved with 10,000 hours of hard work.
  * Where you were born + when you were born + working 10,000 hours (or more) > (is greater than) natural talent.

I know people with natural talent at something who’ve never gone anywhere with it because they lacked ambition and possessed an aversion to (or fear of) hard work. I know people who created extraordinary lives for themselves with their talent. There’s little doubt in my mind that work and experience can help you hone and harness natural talent. But it can’t replace it. Maybe I’ve hung around too many musicians and artists, but I believe there’s an intangible “something” that natural talent brings to the equation that simply cannot be matched by learned skill.

Talent exists at a cellular level. It affects how you experience the world with your five senses. Natural talent frames, from the start, how you see the world and all that’s in it. It frames how you process information for your own understanding, how you interpret what you see, how you transform what you know into something that the world—or some part thereof—can subsequently use. Natural talent overrides many of the objections to pursuing an activity that someone not similarly talented would have to beginning the pursuit. Someone with talent for neurosurgery has no reservations about the years of education, training, expense, and sacrifice that are required to become a surgeon. Someone who is capable of learning to be a surgeon—but who lacks a natural talent for it—would be overwhelmed by the work and not interested in pursuing it.

To say that something can be achieved with hours upon hours upon hours upon hours of hard work, and not so much by natural talent, is an oversimplification of a complex human process that is driven by intelligence, creativity, emotion, psychology, desire, and so on. A person born with a gift for language and communication, even with 10,000 hours of work, will not be nearly as effective in a career in biostatistics as they would be in a career that calls upon their talents. Using his logic, I could have been a successful computer programmer except that I would have been miserable at a personal level, because I would have been doing something that ran counter to the gifts I was born with. I didn’t enjoy my programming courses. I worked hard for the grades I got and felt out of my element. Sure, I could have stuck with it, overcome initial challenges, and made a living at it.

But I didn’t want to.

Which brings me back to my earlier point—that natural talent drives desire, fuels passion, feeds energy, defines goals, maps a course. It makes Gladwell’s 10,000 hours look manageable, not insurmountable. It makes challenges look like welcome creative opportunities. It makes Gladwell’s 10,000 hours look like a darn fine way to spend a life.

To deny the importance—even the existence—of natural talent is to devalue the singular contributions made by the people through whom ideas and visions and theories came. It is to say that anyone could have done what Albert Einstein did, that anyone could have seen the world in the same way that he did—he simply got there first.

What Gladwell’s book should offer all of us is another opportunity for self-reflection, the kind that Tom Johnson openly engaged in on his blog. An opportunity to recount and document our individual journeys, the crossroads we’ve navigated, the decisions that we regret or revel in. A “how did I get here from there” analysis can make us more comfortable with and accepting of who we are, where we are, the decisions we’ve made, the value we offer, and where we are headed. If it doesn’t lead to greater self-acceptance, it should lead to greater self-awareness. Such analysis can dispel any victim myths we may have been telling ourselves (and, likely, others), where we’ve been too passive, where we’ve clearly been “working in flow” (read: on our path), and what things make our hearts sing or sink. It can illustrate for us whether we need a course correction.

This lifeline/timeline analysis is one that every career and life coach makes you do when you go to them to “sort things out.” In Tom’s case, his analysis proved to be a validation that he is where he wants to be and, maybe, is “supposed” to be. For others, the analysis may lead to an entirely different conclusion about their own lives. In either case, the folks doing this analysis become more conscious of what they’re doing, thereby kicking themselves off auto-pilot. Extending the analysis to look at the activities and decisions of people we respect and admire—without comparing ourselves to them—and being aware of our reactions to them is almost as telling as self-reflection. Does watching a former colleague turn being laid off into a launching pad for their own business or career change stir up envy, or old dreams and goals of your own? Or does it help you reaffirm why you’re content—consciously content—with where you are and what you’re doing?

Like Seth Godin, I may not always agree with Gladwell but I can always count on him to provoke thought, to make me, if not change my beliefs and opinions, reaffirm to myself why I formed them in the first place.

More…

Writer’s Toolkit: Cleaning The Crap Off Your PC

Years ago, when we launched Scrivener as a newsletter, we had a regular feature called “Writer’s Toolkit,” which was a sampling of the tricks, tips, and tools that were shared on the SIG listserv. (Grant Hogarth, a senior member of both the STC and our SIG, was by far the most frequent contributor.) It’s a feature worth reviving for the blog.

While cleaning out my overstuffed mail folders, I found dozens of Toolkit-worthy e-mails that I’ve been saving. One such group of e-mails was about cleaning junk off your hard drive and clearing out unnecessary processes. Listed below are the tools that were recommended, and one resource site:

• 19 Tools to Get the Junk Off Your PC from PCWorld
• PC Decrapifier
• CCleaner from Piriform Ltd.
• System Mechanic from Iolo Technologies
• Answers That Work
• jv16 PowerTools from Macecraft Software

I can vouch for the freeware program CCleaner, which is a great tool for routine cleaning of your drive, particularly after you’ve been on the Web for any length of time. You can have it search for the whole default list of garbage-file generators, or some customizable subset thereof. It also scans for and repairs Registry problems. It installs quickly, updates quickly, and is not a resource hog. Although it’s freeware, I encourage folks to throw a few bucks to Piriform; it’s well worth it.

System Mechanic is a full suite of optimization tools, from defragmenting hard drives to cleaning out Registry junk to optimizing various performance factors and more. I have an old version, which can be a bit of a resource hog but my geek friends tell me that more recent versions of System Mechanic are less greedy for resources.

Have your own favorites? Share ‘em here!

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…

SIG Activities at the Annual Conference

With the annual conference coming up in just a couple of months (less a few days), the Lone Writer SIG managers are starting to get some questions about SIG activities in Atlanta.

The short answer is: Details are still being worked out.

The long answer is that discussions just started yesterday on our listserv about options for the after-hours SIG get-together. If planning this year follows the same course as in previous years, date, time, and location usually gets settled a couple of weeks before the conference. When the details are available, we’ll post them here and send them out on Twitter.

With respect to the SIG “business” meeting, room reservation requests were sent in last week and conference organizers will let us know the date and time of our SIG’s meeting. (The SIG meetings have typically been early in the morning so as not to compete with the conference sessions.) Details will be posted here and on Twitter.

Stay tuned…

More…

Word To Excel By Way Of HTML

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.

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…

Why Tech Writers Feel Like Bartleby The Scrivener

Sometimes, being a technical writer is enough to make you run screaming for the comparable simplicity of a sales clerk job at Barnes & Noble. Or to a cabin deep in the woods of Western Massachusetts.

Mars Girl, a tech writer in Ohio, wrote about her frustrations with her contract job—which has not, to date, yielded the professional growth and fulfillment she’d hoped for.

I laughed a lot while reading her saga—laughed out of amusement, empathy, and commiseration. In her paragraphs, most any working tech writer will find something they relate to. The stories we all could tell would keep Scott Adams in Dilbert storylines for decades.

Too many folks, not just tech writers, work for companies that seem caught in an endless loop of misdirection and no direction. They have processes and flowcharts that, while detailed, don’t always reflect what’s actually having to be done on a day-to-day basis—many times at management’s own instruction. This Shtikl comic, I think, perfectly illustrates these environments. The sad thing is that the folks who can least afford to be lost are the same ones who are lost—and clueless about the fact that they are. 

Similarly, there’s the environments where there actually is a direction—it just seems to take unnecessarily long to get from Point A to Point B. I call it management by cowpath. If you ever read the old “Family Circus” cartoons, you can probably remember the circuituous paths home that Billy would take from school or Jeffy would take from a friend’s house. A Brevity comic strip used a tumbleweed and a flock of sheep for its metaphor; coming to the top of a hill, the sheep leading a flock of hundreds says, while looking at what was in front of them for presumably miles, “Oh brother, we’ve been following a tumbleweed this whole time.” You know you’re headed somewhere. Eventually.

We’ve all either been there—or are there. The best you can do is give it a good college try while simultaneously planning your exit strategy. And, in the meantime, when the exasperation runneth over, perhaps another Shtikl comic’s blunt sarcasm will help remind you that you do have comrades-in-arms. And that you’re not the one who’s crazy.

More…

‹ First  < 2 3 4 5 >