March 2009

Recent posts from my favourite technical writing bloggers

These are the latest posts from the technical writing blogs I read most often. You can find more information about each of these in my list of tech writing blogs.

RSS feed If, like me, you reckon all of these blogs are worth keeping an eye one, you can subscribe to a combined feed of all of them using this technical writing blogs mashup feed.

 

I’d Rather Be Writing – Tom Johnson

Organizing for Learnability [Organizing Content #25]
Last week I attended WordCamp Utah and spoke with one of the “happiness engineers” who works at Automattic. (Automattic is the the company that provides WordPress.com and also leads development of the open-source WordPress software.) The happiness engineer, Sherri, told me about a new alternative to the Codex and WordPress.com Help for ramping up on WordPress: learn.wordpress.com. At first glance, learn.wordpress.com looks plain and somewhat un-instructive, put together by someone who ... more »

 

justwriteclick – Anne Gentle

Web Analytics for Technical Documentation Sites
I’m studying different help sites and applying web analytics. I wanted to write up some of the processes, potential wins, and possible short comings of web analytics for technical communication. When I spoke with a few Google technical writers at the STC Summit, one of them confirmed that their performance reviews include a web analytics [...]

 

Technically Speaking – Paul Pehrson

When the “right” tool isn’t the “best” tool
Not too long ago, I found myself stuck between a rock and a hard place. I work for a large organization (30k+ world wide workforce), and I’m just one tiny fish in a very large lake. I was asked to provide help content in the form of a getting started guide for a piece of [...]

 

ONEMANWRITES – Gordon McLean

Content Aggregation
I have an admission. I’m lazy. I work hard to get around that basic character trait but it remains there in the background, nagging away at me. Professional pride stops it influencing my work (I manage a lean, mean to-do list to keep me on track), but when it comes to things on the periphery [...]

 

UAX (User Assistance Experience) – Michael Hughes

Menu Blind Spot
I'd write this one off to stupid user (moi) except that I saw it a lot when I was a usability tester. I wanted to change presentation colors in my email client. I was pretty sure I did that in Tools > Preferences. It is important to note that my opening assumption, I repeat, was that I would find it under Tools > Preferences. I clicked on Tools.I couldn't find Preferences.After some frustrated

 

When the muse strikes! – Rahul Prabhakar

 

ffeathers – Sarah Maddox

TCANZ 2010 day 2 – Tools for collaboration, management, and delivery of information
I’m attending the TCANZ Conference 2010 in Wellington, New Zealand. Rowdy Bristol gave a session on “tools for enabling collaboration, management, and delivery of information on the web”. These are the notes I took during the session. All credit goes to Rowdy. Any mistakes are mine. Rowdy started with a hilarious sequence of slides outlining [...]

 

Gryphon Mountain Journals – Ben Minson

Deleting a Topic from RoboHelp and Subversion
As you’re developing a help system and updating content, it sometimes becomes necessary to delete a topic file because the information is out of date or should be combined with other information. When you’re using both RoboHelp and Subversion, it’s easy to mess things up doing this. It’s important to delete the file in RH [...] Related entries:

 

Communications from DMN – Aaron Davis and Scott Nesbitt

Weekly links roundup
10 steps to creating a numbered heading style in Word The top 15 Android apps for business Use your support emails as your help files Should writers and editors learn technical skills? Yes! 7 tips for marketing your freelance business offline Related posts:Weekly links roundup Weekly links roundup Weekly links roundup Related posts:
  1. Weekly links roundup
  2. Weekly links roundup
  3. Weekly links roundup

 

A Techie Tech Writer Blog – Janet Swisher

Wordless instructions are not universal

My gloss on this picture: If you're confused, go back to the IKEA store and borrow their phone with a really long extension cord, so you can call support from the parking lot.

Last weekend, my husband and I helped a couple of friends, Amanda and Stephen, move into their first owned home. They took the occasion of this move to upgrade and expand their furniture collection with several new items from IKEA. And they hired a service to assemble the furniture. I hadn't realized that such services existed. I'll have to keep that in mind as an alternative career if I get burned out on this tech writing thing. I'm blessed with the right combination of visual, spatial, and motor abilities such that I actually enjoy assembling IKEA furniture. Not everyone is so fortunate (if you want to call it that). As Stephen said, "If I had to do all this, the result would be divorce and me burning the house down." As it happened, a miscommunication meant that the service didn't have time to assemble all the items, so I got to do a couple of them after all.

IKEA is known for keeping their prices as low as possible, and one of the ways they do that is with almost completely wordless pictorial instructions. The fewer words they use, the fewer words they have to pay to translate. The instructions for a bookshelf I recently assembled for myself included a single note that was translated into 18 languages, and therefore took up about half a page. Minimizing text also reduces page count and printing costs. Another way that IKEA reduces printing costs is by using newsprint-quality paper for the instructions in some (but not all) products. Unfortunately, this means that the print quality is also low, and fine details can be difficult to discern for all but the sharpest eyes. Figuring out how pieces fit together can depend on matching the positions of tiny dots in the diagram to those of holes in the physical pieces, so fine details matter a lot.

Wordless instructions may transcend language, but that does not mean that they are universally usable. Some people are just not visual learners. Amanda said, "I can't make sense of those diagrams, but I can do it when Janet explains it." She's more comfortable with verbal instructions than visual ones. In other cases, physical limitations are the issue rather than cognitive style. Stephen is an awesome photographer; he's also visually impaired, so those tiny dots on newsprint are a non-starter. The same can be true for those of us who find our arms getting shorter as we get older and our near-distance vision degrades.

No doubt IKEA has carefully weighed the costs and benefits, and determined that wordless instructions make the best sense for their business. Wordless instructions are sufficient for the majority of their customers, and many of the rest can be helped by phone support. They leave open a market opportunity for furniture assembly services, and IKEA doesn't mind ceding the space, as long as they still sell bookshelves. I wonder if there's also a tiny market niche for verbal instructions to go along with the pictorial ones.

 

TECHWR-L

Technical Writing in a Quality Management Environment

by Irv Boichuk

I was browsing through a long list of contract opportunities for technical writers on the Internet, when I spotted one from a manufacturing company looking for a documentation specialist. It stated that the perfect candidate would have "a working knowledge of TQC, TQM, ISO, QS9000, Kaizen, Gemba, and Hoshin." If you read between the words, it was obvious that the company was desperately seeking a quality management program in their operations, but had no idea what they wanted!

read more

 

Shanghai Tech Writer – Susan Wu

Google China is Hiring

Google China is Hiring is a post from: Shanghai Tech Writer

Google China is Hiring is a post from: Shanghai Tech Writer Google China is hiring! Below is the video campaign posted on YouKu, which will also be shown in theaters across the country prior to the film "Inception." See the Google China Job page for job openings. Share and Enjoy: Related Articles:Competing for Jobs in China (1)Resources for [...]

 

Kungfuwit: Tech Writing FU

About content chunking with drop down text and togglers
Are you using condition tags to separate content for different users and roles in an organization? The MadCap Software blog has an article about chunking content with drop down text and togglers – Chunking Content for User Roles. Selectively including or excluding content using conditional markers is something that most Flare authors are accustomed to. [...]

 

UXmatters

Personas: Explorations in Developing a Deep and Dimensioned Character
By Traci Lepore Published: August 23, 2010 “Who has been frustrated or had issues with trying to use personas effectively? … Personas are often emotionless, easily forgotten or dropped altogether, and difficult to share with others in a way that got them engaged.” I started off a recent presentation by asking how many people in the room had used personas. About 85% of around 50 people raised their hands. Almost every one of these people also raised their hands to the question Who has been frustrated or had issues with trying to use personas effectively? When I asked what was causing these issues, people responded that personas are often emotionless, easily forgotten or dropped altogether, and difficult to share with others in a way that got them engaged. Not surprising really. These are the same issues I’ve been tackling when it comes personas, too. I have felt their pain. In my column “What’s My Persona? Developing a Deep and Dimensioned Character,” I talked about developing believable characters for personas that are emotionally engaging to help overcome these issues and make personas more effective. To solve some of the pitfalls of developing and using personas, I proposed activities as simple as doing a dramatic reading of the personas, as well as more complicated character-development activities that have their basis in theatrical training. If we are going to begin to address these issues, we need to get at the root of the problem—our empathetic understanding of our users. Having empathy for users and understanding their needs doesn’t come from reading words on a page. It doesn’t come from statistical analysis of demographics either. It comes from truly embodying and experiencing the character of a persona, so it becomes ingrained emotionally and physically in our memories. Actors understand this. From the time Stanislavski began teaching Method Acting—a process of transformation in which actors begin to take on the true nature of a character—actors have referred to this moment when they realize a character’s emotional memory and have truly become the character as the moment of embodiment. I’ve recently had the opportunity to explore these ideas in a real and practical setting and want to share my experience and the feedback I received with you.

 

Usable Help – Gordon Meyer

Visual Touch-ography
A picture is worth five words.

 

A Tech Writer's World – Andrew Brooke

A Magically Magical Product that's Full of Magical Magic!
Apple's a funny entity, somewhere between a corporation and a religion. I'm not a "Mac" person per se, but concede their products are among the few that actual make the news. Other companies would kill to such have constant free publicity. Can you imagine if Chrysler's latest attempt to build a car actually made headlines? It'll be a cold day at the North Pole before that happens.

I also appreciate the beauty, elegance, and extreme usability of their products. My first computer, in fact, was an Apple - an Apple IIc laptop, way back in 1985 - I don't think they even had cars back then.

What a dog the IIc was. It came with a small 9" ugly puke green monochrome screen and had no hard drive - just a built-in 5 1/4 floppy drive. You had to load the software from the floppy each time. The size of the documents was limited to about 9 pages. Still, it was miles ahead of my old typewriter, and did get me through college.

How times have changed. Apple's more recent devices are impressive, from the all-in-one desktops, to their phones, and most recently, the iPad.

I've played around a bit with the iPad and have to admit it's pretty cool. However, I don't like the fact that, unlike a notebook (or smaller netbook), it lays flat; that is, the virtual keyboard is embedded into the screen in one piece, meaning you can't fold it. It's just not ergonomic for me - I like to have the keyboard separate from the monitor and at a right angle to it. But that's just me; millions of other users don't care, as they have actually bought the thing.

Two of the new owners are my parents, who are Mac people. They recently bought an iPad, and asked their techie son to help set it up. I slowly undid the wrapping and beheld its awesome beauty and simplicity. I turn it on, expecting to see the standard desktop I had seen in the store, but instead a most unusual thing appeared - an image of a USB plug and then the word "iTunes".

Huh?

I quickly deduced that the setup procedure involved connecting iPad to the computer, and then opening iTunes. What a waste of good monitor space. Instead display an obscure image and one word, the iPad screen should have given clear instructions:
  1. Connect your iPad to your Apple computer.
  2. Open iTunes.
  3. Follow the setup instructions from the iPad menu in iTunes.

I'm not exactly sure why the iPad doesn't have a separate setup and configuration application, but I guess it's because since iTunes and iPad start with the same letter, Apple felt they should live together.

I proceeded to run an update program to ensure I had the latest version of the "magic". It failed. I tried it again and again it failed. I was taken to a troubleshooting page which listed various solutions, some simple and some about as simple as Japanese mathematics. I thought Apple devices were supposed to make things easier; I certainly wasn't feeling the magic.

Anyway, by a miracle, I was able to restore the iPad to its factory state. I set up a WiFi connection; it worked, but it was so s-l-o-w.

I told my folks to call their "Mac" guy to figure it out.

Apple lovers - I hate those guys....

 

Core Dump – Keith Soltys