I recently attended Confab in Minneapolis. I was one of about 5 technical writers among the 650 attendees, which is why I found it surprising to hear Kristina Halverson say, We can learn a lot from tech comm. Let me repeat that. We can learn a lot from tech comm. I felt pleased to hear this shout-out to my profession, and then tried to unpack exactly … more »

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 … more »

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 … more »

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. … more »

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 … more »

The following is a guest post by Sarah Maddox, a technical writer at Atlassian. 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 … more »

This past year I learned a few things. As I approach 2012, I’d like to note what 2011 taught me: Writing documentation in a wiki suits me for the same reasons I enjoy interacting on the web. The web is interactive, alive, dynamic, collaborative, fresh, and unlimited in potential. A wiki, being online, allows me to partake in the same game-like, community-rich environment that I … more »

In my last post on wikis, Mark Baker added an astute comment: I’m not a wiki fan myself — I’m a structured text guy bred in the bone — but I am fascinated by the trend, and by the variety reactions to it. Wikis started more as a cultural statement than a technology. They were a tool for the democratization of content, the intent being … more »

Last week I was feeling a bit stretched out about not having enough time to accomplish everything I needed to do. Granted, I gave several webinars to a total of 2,000 people, which was somewhat stressful, but I was more stressed about the fact that the help material I’d created could have been much better if I had only more time to focus on it. … more »

Two powerful trends in tech comm seem to be moving in different directions: social media and structured authoring. I have used a wiki as my primary format for documentation for the past year and a half. I tried to corral a group of volunteer technical writers to edit and update the wiki, because I embraced the idea that collective intelligence beats the individual thinker in … more »

I was talking to a colleague today about wikis when he mentioned Google, and how Google has such a brilliantly simple solution that allows users to find content. With Google, there’s a search box. The users type keywords they want information about, and most of the time Google returns brilliantly relevant results. While some credit is certainly due to Google’s Pagerank algorithm, what enables findability … more »

Alan Porter’s Wiki: Grow Your Own for Fun and Profit, published by XML Press in October 2010, provides an excellent introduction to wikis. This is a short, easy-to-read book spanning about 150 pages. Alan has a keen sense of organization and liveliness in his writing. He carries the gardening metaphor throughout the book, ending with five solid case studies and an extended response to common … more »

One of the sites I’m working with lately at my job combines a forum (vBulletin), blog (Joomla), and wiki (Mediawiki) into one experience. Each of these tools does a great job at what it was designed to do. They’re three separate platforms skinned and linked together. I used to think the site was a hodgepodge of software platforms, but now I see that these three resources … more »

In my last series post on organizing content, I argued that traditional help authoring tools will be replaced by web platforms suitable for authoring help content. Web platforms have many advantages over help authoring tools. They provide everything from search engine optimization to interactivity and social media integration. Some of the more common HAT features, such as single sourcing and print, may not be as … more »

Yes, I am continuing this series on Organizing Content, so if you are tired of it, check back in a while. My goal is to reach 100 posts on the topic. An Electricity Fast First, a brief bit of news. All the lights in my house are off because Jane wants to do an electricity fast. It’s a Thoreauvian experiment to see what you gain when you … more »