Lately I’ve been converting my documentation over to a SharePoint wiki and have had days where I felt totally liberated and others where I wanted to go into my Control Panel and remove every Microsoft product I have installed on my computer.

Liberating

Here’s what I find liberating. Most wikis can easily degenerate into a chaotic disaster, with links nested on pages pointing to other links on other pages, with no clear sense of where you are or how deep the wiki goes. One writer at Doc Train told me her company’s wiki was an “unmitigated disaster.”

With SharePoint, you can get around this chaos by adding columns on wiki pages. The columns are similar to metadata fields for the page. You can add a drop-down box requiring the user to select a category for the wiki page, and the role, and any other ways you want to classify the wiki page.

Then you use SharePoint’s sorting and grouping functions to create various views for your wiki. These views use the columns/metadata fields to sort your pages by category, by role, or other methods. This is liberating because it allows you to impose order on what might otherwise become chaotic.

Read the rest of this entry »

I’m giving a virtual presentation to the STC-Phoenix chapter tomorrow at 6:15 pm Arizona Time (which right now is the same as PST). The topic of my virtual presentation is “Combining Social Media with Help Authoring.” See more details here. It costs $10 and should last about an hour. Even though it’s coordinated by STC Phoenix, anyone interested can sign up.

May 15, 2008 Update: View the PowerPoint for this presentation (.ppt).

Download MP3
Duration: 18 min.

Audio clip: Adobe Flash Player (version 9 or above) is required to play this audio clip. Download the latest version here. You also need to have JavaScript enabled in your browser.

Stewart Mader was one of the coolest people I met at Doc Train West 2008. He is a person driven by his enthusiasm for wikis. Read the rest of this entry »

Download MP3
Duration: 43 min.

Audio clip: Adobe Flash Player (version 9 or above) is required to play this audio clip. Download the latest version here. You also need to have JavaScript enabled in your browser.

In this podcast, I talk with Alan Porter, vice president of Operations at WebWorks, about the Web 2.0 technologies they’re using to reach out to their customer base. In addition to using blogs, wikis, and social networks to connect with customers, WebWorks also uses wikis to facilitate communication and collaboration within their company.

Alan says they consider themselves a “wiki-driven company” because the wiki drives the way they do business. WebWorks has an internal wiki (which replaced their old intranet), a projects wiki (used to communicate with their customers on project work), an external wiki for their help center (where customers can interact directly with developers and support), and a wiki for organizing their upcoming user conference.

Read the rest of this entry »

Sarah Maddox gives us a interesting glimpse into the life of an agile technical writer, or more descript, extreme technical writing, XTW. If you work in an agile environment, definitely check out these two posts:

• The Agile Technical Writer (I)
• The Agile Technical Writer II

(Although ffeathers is already in my feedreader, I missed these posts in the firehose of information and didn’t discover them until I read Anne Gentle’s latest post, How to be an Agile Technical Writer with a cool acronym like XTW.)

Here are a few excerpts from Maddox that hit home with me:

Things change, and we need to change with them. If we spend too much time setting requirements in stone, they’re out of date by the time we write the software. And then there’s no hope that the documentation will be up to date.

Totally agree with this one. I went from a traditional all-requirements-up-front environment to an agile environment, and the difference in software quality is pretty astounding. I’m convinced that people don’t know what they want until you deliver them an actual product. Read the rest of this entry »

Occasionally people send me links to check out, and they encourage me to use them as fodder for my blog. I’ve let them build up a bit this past month. Here are three. (I’m copying and pasting from their emails — I hope that’s all right.) I haven’t actually explored them yet, but some might be interesting. Let me know if you have any feedback. Read the rest of this entry »

Ann Gentle of BMC has been researching the use of wikis in documentation. Although wikis have been around for at least ten years, they are finally getting more attention. Ann writes,

It’s funny, in an early blog post I wrote on the internal blogs at BMC I said that I did not see how wikis would be used successfully for technical publications. I have since changed my once low opinion of wikis but I still see them supplementing other documentation, not substituting completely for technical documentation. I’d welcome discussion about wiki as standalone or supplemental end-user documentation. What do you think? Should the merits of wiki for certain products win out as the exact right documentation for that particular product especially one either related to an Agile methodology or social media? Or are wikis relegated to an upgrade to the customer support forum with a kludgy way of entering the information and no good method for outputting an information deliverable worth reading?

Read the rest of this entry »

If you glance at the instructions for installing Mediawiki, it looks like you have to run complicated scripts with shell access to your server and other geeky stuff. In reality, it’s about as easy to install as Dokuwiki — assuming you have a typical hosted account, such as with Blue Host or Lunar Pages. Here’s how to do it.
Read the rest of this entry »

This is a list of the top 57 wikis (by rank). It’s interesting to see how they are being used and which wikis they’re using. One thing Katriel Reichman said in the wiki interview the other day is that wikis are often best used when the topic is reference information. I haven’t gone through each of the 57 wikis, but I bet one could learn a lot by perusing them for a few days.

I found this list by searching for wikis in del.icio.us, the most popular social bookmarking site.

The other day I interviewed Katriel Reichman about wikis and he recommended Dokuwiki and Mediawiki. Mediawiki runs Wikipedia, so you’re probably familiar with how it looks. After the podcast I installed Dokuwiki to create the Tech Writer Blog Directory that I mentioned in an earlier post.

Dokuwiki turns out to be incredibly easy to install. The ease of setup and use is something a Doc Train speaker said about most every Web 2.0 technology — the technology part of Web 2.0 is easy; shifting the mindsets of people and organizations, on the other hand, is hard.

To illustrate how easy the set up is for Dokuwiki, I made a two-minute installation video. I’m a new Dokuwiki user, but in just playing around with it a short time I was able to figure out what I needed to do. Enjoy the video.

One of my readers, Dan, has a lot more experience with Dokuwiki. Maybe Dan can provide some tips on the pros and cons of using Dokuwiki.

Other Helpful Dokuwiki Resources

• Written instructions
• General Dokuwiki info
• Dokuwiki manual