I’d Rather Be Writing – Tom Johnson

This is a guest post by Cathy Wildhaber about her experience implementing a wiki in her department. Cathy is a technical writer in Kansas City. For the past 4 years, she has worked for a company that provides computer systems and services to financial organizations.

Ever take a look at some slick wiki technology and think “Wow, that’s really cool…I want one”? I did, and the results (an internal wiki for the documentation department where I work) were…less than stellar. Here’s how you can avoid my mistakes.

I had been working on a continuing education SharePoint site for the department. There was a wiki webpart available in SharePoint, and I became intrigued. What better way to help department members increase their knowledge about the profession than by harnessing our collective brainpower and talents! We could create collaborative summaries of training we’d attended! The intern could create a “new hire” section! We could have a knowledge base! How cool! Read the rest of this entry »

If you have a way of tagging or marking the good content you read online — such as adding it to a specific category on your blog, bookmarking it through Delicious, or putting the link on some other online site — send me the RSS feed for it, and I’ll add it to the Yahoo Pipes aggregated feed that I have going with Writer River.

Here’s what the Yahoo Pipes feed looks like at the moment.

Writer River Yahoo Pipes feed

It’s simple compared to other Yahoo Pipes feeds. Basically the pipe takes RSS feeds from as many sources as I add here, sorts the posts by the date published, filters out any duplicate titles, and then merges all the information into one RSS feed. Writer River then displays this RSS feed on its home page. When you subscribe to the Writer River RSS feed (or when you subscribe to Writer River’s email delivery or Twitter updates), you’re also subscribing to this same Yahoo Pipes feed.

I’m convinced that human-assisted aggregation and filtering, with the help of such tools as Yahoo Pipes, is the trend for managing the deluge of information online. Since everyone is an author, publishing on separate sites, RSS is the only way to keep up. And people are publishing like mad, pushing out about a million posts a day. Read the rest of this entry »

With all the talk about latest trends and avoiding extinction as communicators, and integrating web 2.0 and wikis, blogs, podcasts, and other interactive social media into help, it’s a good time to look at how Google — practically the leader of the web — does help.

Last week Google released Google Voice, a service that allows you to integrate all your phones into one number and includes a host of features, including voice mail, recording, conference calling, and other services.

To help users get started, Google Voice has a list of 20 short videos. Only the overview video contains animation. It’s certainly the video they’ve put the most work into, and it also functions as marketing collateral.

The other videos are fairly simple, with short looping background music, professional voice talent, and a read script. The defining quality is that each video is short, some as short as 25 seconds. Read the rest of this entry »

Beginning writers trying to break into the field of technical writing face a paradox: almost all jobs require experience, but they can’t get experience without first having a job.

In the past, I’ve recommended that beginning writers create documentation for any open-source project they can find, such as WordPress, Audacity, or projects on SourceForge.net. However, our organization now has about ten open source projects that would provide an ideal opportunity for entry-level writers to gain real experience in technical writing. These projects are located at https://tech.lds.org/wiki. Read the rest of this entry »

Trees, maps, and theorems, by Jean-luc Duomont

I’m currently reading Trees, maps, and theorems: Effective communication for rational minds, a new book by Jean-luc Doumont. The reason I wanted to read the book is for Jean-luc’s expertise in visual design and page layout, because I thought it could help me design better quick reference guides. Although very little of the book deals with design and is more geared toward engineers (the “rational minds”), he does address page layout and intuitive design in a couple of sections. Here are a few passages of advice:

• “Leave more distance between unrelated items than between related ones.” For example, headings should be close to the text they belong to, rather than equidistant between the last section and the new section. (This principle is termed proximity in Robin William’s Non-Designers Design book.)
• “Be visually consistent: format identical items identically, similar items similarly, different items differently.” This helps the reader understand and predict the relationships between the various information units at a glance.
• “To indicate hierarchy, display more prominently those items that rank higher or that are more important.” Again, in other circles, this would be the principle of contrast.
• “Make sure that each page guides the readers visually along a useful reading sequence or, alternatively, that it gives a clear picture of possible entry points.” This principle is especially important. A document without a clear focal point for readers can lead to a confusing design, such that you look at it and you’re not sure where to begin because you’re eye is drawn everywhere and nowhere (p.73).

Read the rest of this entry »

I’m trying something a little new on my blog. Previously, every time I read a cool post, I submitted the link to Writer River. The problem with that, however, is that posting to another site isn’t such a smart search engine optimization (SEO) strategy. Using the Writer River method, people who follow trackbacks don’t follow them back to my site (idratherbewriting.com), but rather go to another site (writerriver.com).

Additionally, it’s more beneficial for me to link to others from my idratherbewriting.com site, because it has a higher authority than writerriver.com. Links from higher authority sites are more beneficial in transferring search engine visibility than links from lower authority sites. For example, a link from NYTimes.com will push you to the top of Google results while a link from Sam’s vacation blog probably won’t have much influence.

So here’s what I did to better search engine optimize my site. I created a new section on my site called What I’m Reading. The page shows all the posts I’m reading (which I want to share), with short commentaries or summaries about the content. This way I keep the keywords and links on my site. I’m hoping that this strategy will create more pull back to my own site and will increase the rank of those I link to, more so than links from Writer River. Read the rest of this entry »

Last Sunday we celebrated Father’s Day. I don’t know if this is a global holiday, or if it’s just a U.S. holiday, but reading an article in the Father’s Day edition from the New York Times made me think about my role as a father.

I am a lot of different things to different people. To some, I’m a blogger and podcaster. To others, I’m an employee and team member. To others, I’m a church member and scout leader. To others, a basketball player. To others, a friend. To my wife, a husband. But to three young girls, I’m a dad.

In the NY Times article, Michael Winerip explains that some years ago, he was putting in 11 hour days with a 2.5 hour daily commute. When he finally arrived home in the evenings, his children would catch just a glimpse of their father before bedtime. Winerip was upset about missing his kids grow up. And his wife felt like her career was suffering due to being off track as a stay-at-home mother. So they switched, and he became the stay-at-home parent to raise their children while she worked. Read the rest of this entry »

Fictitious documentation refers to documentation that fails a lie detector test but which passes the project manager’s approval.

Here’s the situation: You’re writing documentation that will be printed in large quantities. At the deadline for printing, the software still has a few bugs. If you mention the bugs in your documentation, it’s likely the printed documentation will still be around after the bugs are fixed, making your documentation out of date. If you don’t mention the bugs, it’s likely that users will be confused until the bugs are fixed.

Do you lie and pretend the bugs don’t exist? Do you boldly write results statements that you know are pure fiction? Or do you describe the bugs in their nitty, gritty, ugly details? Read the rest of this entry »

Last week I wrote a post about avoiding extinction as a technical communicator. The basic idea was that you have to keep up with the learning styles, preferences, and behaviors of your users to survive. That often means avoiding the long manual and incorporating more interactive, collaborative, or audiovisual means of instruction.

Almost the exact same argument could be made about the STC and its financial trouble. In case you haven’t heard, the STC’s finances are facing crisis proportions. Unless membership stabilizes, it could go out of business in a couple of years. Read the rest of this entry »

Download MP3
Length: 11 min.

Forms that Work

In this podcast, Caroline Jarret talks about her new book, Forms that Work: Designing Web Forms for Usability, which she co-authored with Gerry Gaffney. Forms she discusses go beyond merely the type of IRS forms you fill out at tax time. Every website usually has some online form to collect information from users, from registration information to subscription information to purchasing information.

Caroline talks about the perceived value users must feel in order to part with their precious personal information. She explores why people dislike forms, and how companies can get around these dislikes to increase the usability of their forms, moving beyond appearance and layout and instead focusing more on relationships and conversation.

See the companion website to Forms That Work.

Buy Forms That Work: Designing web forms for usability from Amazon.