I've been reading Sarah Maddox's new book, Confluence, Tech Comm, Chocolate, and have been impressed. I enjoy the energy and speed in Sarah's writing. If you've read her blog before, her book has the same tone. This is not a book review, because I'm not yet finished with the book. But it doesn't take too many pages to come to some realizations worth noting. My primary realization: I wish I had a Confluence wiki rather than a Mediawiki wik...
This week, as I was riding my bike to work and listening to Robert Jordan's The Wheel of Time: The Eye of the World (a classic fantasy/adventure book), one of the characters -- was it Bayle Domon, the pirate? for the life of me, I can't remember, nor can I find it, but he says something like this to Rand, one of the protagonists: Sometimes asking questions is more important than finding answers. This sentence rang instantly true in my mi...
At work I have often grumbled about the fact that we have both a blog and a wiki, and that content shared between them sometimes seems redundant and unnecessary. However, I have since come to realize how well blogs and wikis fit together. I think it makes sense to have both -- at least in my authoring scenario. In short, wikis are suited for information that doesn't expire in a short time, while blogs are better for short-lived news. The ...
The 80/20 rule, or Pareto's Principle, states that 80 percent of the effects come from 20 percent of the causes. Applied to help authoring, this could mean that from 100 help topics you write, about 20 of the topics will be viewed 80 percent of the time. Designers recognize the applicability of the 80/20 rule on design. Heat maps show that people only focus on about 20 percent of the page. This is where good designers will focus their ene...
I admit that I am developing a love affair with grapefruit. Don't get me wrong -- I love many types of fruit. But there's something particularly special about the grapefruit, particularly ruby red grapefruit. Looking at the following image, can anyone really blame me? Try to restrain yourself from reaching out and eating this grapefruit. I'm not sure if I can even pinpoint exactly why I like grapefruit so much. First of all, it's a fruit ...
Neal Kaplan The following is a guest post by Neal Kaplan, a technical writer at Zuora, Inc. Another post about wikis? Why not! Wikis are great! Just to set the stage, I've been a technical writer for a while now, working for software companies in Silicon Valley. (In fact, I often forget that there are technical writers who don't document software.) I've worked at large companies, where I delivered my source files to a production team and...
A couple of years ago, I wanted to try biking to work and made an initial trial with a hybrid cruiser bike that ended up consuming way too much time (about 2 hrs each way). I gave up on the idea, and then winter came and no one bikes to work during winter in Utah. A few months ago, however, I went to Florida to help out one of my parents. During that trip, I came home with my dad's bike, a Specialized City Globe 7.1, which he could no lon...
One of the challenges with wikis (or at least with Mediawiki) is figuring out how to title pages that all belong to the same product or group. I spent a bit of time researching best practices with this and didn't come up with a clear answer. I tried to also figure out why I'd never come across this page titling conundrum before. Here's the problem. On a large wiki, you have pages about many different products. For simplicity sake, let's s...
Mick Davidson The following is a guest post by Mick Davidson, a technical writer with 20 years of professional writing experience. Before I get started I'd like to thank Tom for giving me this opportunity to bang on about why I think wikis are the future for technical documentation. Like many writers, up to a few years ago I was plodding around using backwoods technology, stuck with systems that had once been great but now begged to be r...
The following is a guest post by Akshay Bardia, a technical writer in Mumbai, India. Akshay Bardia Technical communicators work odd hours of the day as we cater to clients in different parts of the world. So, you could find yourself yawning on the Tokyo shift, worrying about the traffic on the way back in the normal shift, or dozing off during the West coast shift. If you are doing the early shift, while your friends are busy snoring you...
The following is a guest post by Lopa Mishra, a technical writer in Mumbai, India. Lopamudra Mishra At a college reunion party recently, someone asked me what job I'm pursuing. On replying that I'm a writer, a friend jumped in to clarify that I'm a "technical" writer. My friend considers that technical writing has nothing to do with creativity, contrary to "plain" writing which is a highly ingenious endeavor. To be honest, I was of ...
In my writing role at work , I occasionally post updates on behalf of our IT organization to various social media channels, such as Twitter, Facebook, Google Plus, our blog, and a user forum. Most of my activity on these social media channels is sparse and sporadic -- a few minutes on an occasional hour. However, lately I've felt that we aren't tapping into social media's potential. We're hardly using it at all, despite the fact that we h...
In 2004, when I returned from a teaching stint in Egypt and began working as a copywriter for a health company in Clearwater, Florida, my manager insisted that I track something related to my writing. We decided that I would track word count, because this was the easiest thing to track. Each week, I graphed the number of words I published, and during a weekly meeting, I held up my graph. If the number decreased for the week, I formatted t...
I'm attending three conferences this year: Confab, the STC Summit, and Lavacon. Why did I pick these conferences, over others? Ben Minson and me at a previous STC Summit I attended Confab's inaugural conference last year and felt it was a good fit for my web publishing role at work. Although my job title is "senior technical writer," I spend about 60% of my time being a web editor for LDSTech. LDSTech has a blog, wiki, and forum, and in ...
The following is a guest post by Sarah Maddox, a technical writer at Atlassian. Sarah Maddox In a recent conversation, Tom mentioned that he's been pondering this question: "Why, in a time when collaboration is more important than ever, do wikis still remain mostly unused as a help authoring tool in tech comm departments?" Tom asked me to join his ponderings and write a guest post on the topic. Thanks for the invitation and the thought-p...
