I’d Rather Be Writing - Tom Johnson

Download MP3
Duration: 18 min.

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 (right-click, select Save As)
Duration: 43 min.

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

A member on the Online SIG asked the following question. With his permission, I posted it here as well:

My company is looking to single source the documentation my team creates for our products. We need a solution that will be a repository for authoritative versions of documents that many people from several different departments can use to get the documents they need. The solution should also be able to export documents in HTML, XML, Word, PDF, and RTF.

The killer part of this issue is that we would also like to introduce a wiki for our Website support/help pages. So I have been trying to find a single source solution where we can export documents to the above formats, but also import data that is submitted into the wiki back into the “repository” in somewhat of an automated fashion.

I have discovered several single source methods that can produce content in many different formats, but am having a harder time finding a solution that will interface seamlessly with a customer-facing wiki.

Anyone out there had any experience with a single source solution that has a wiki component?

Read the rest of this entry »

Wikinomics explores the economic side of wikis. In this Harvard Business Review (HBR) ideacast, Don Tapscott, author of Wikinomics: How Mass Collaboration Changes Everything, tells a story about a CEO of a gold mining company who embraced wiki principles to boost his company’s revenue from 90 million to 10 billion.

Frustrated by his geologists’ inability to locate the gold in his land, the CEO nearly closed the company, but in a final effort, decided to open up his intellectual property to geologists and engineers around the world to see if anyone could provide better guidance about the gold’s location. The top three responses would be awarded half a million dollars. After evaluating the responses, he selected the top three and awarded the prize money. But then the really interesting part begins. Read the rest of this entry »

If you’re interested in learning more about the wiki, blog, and RSS functionality of SharePoint 2007, watch this movie from Microsoft’s Channel 9.

To create a new page on the microsoft wiki, you just surround a name in double brackets, like this [[Getting Started]]. When you surround a word in double brackets, it becomes blue and underlined (i.e., a link). When you click the link, a new page is created. When the new page is created, the underlinine disappears and it just remains blue. It is extremely easy to create new pages in the wiki, and I think that’s the strength of SharePoint 2007’s wiki functionality.

Read the rest of this entry »

A RoboHelp to Wiki conversion tool has been announced. This tool will convert your RoboHelp project over to Mediawiki (Mediawiki is the same tool used to create Wikipedia). Other tools already exist that convert HTML pages to Mediawiki pages, but this RoboHelp2Wiki extension apparently allows you to convert batch files all at once. Here’s an exerpt from the developer’s blog:

Read the rest of this entry »

I was talking to Charles Arnold after the last STC-Suncoast chapter meeting about using wikis as project documentation tools. Neil Perlin just presented on Web 2.0, and referenced James Surowiecki’s The Wisdom of Crowds: Why the Many Are Smarter Than the Few and How Collective Wisdom Shapes Business, Economies, Societies and Nations. Surowiecki’s main idea is that collective wisdom almost always outstrips individual wisdom.

I was thinking about this today as I continued documenting our customized version of CRM, a client relationship management application from Microsoft. The IT team implementing it consists of about 30 people. Several SMEs know the product backwards and forwards. There’s a training department that is leading several sessions on it, and a support center with some sharp troubleshooters who also know the product well. Then there are business liaisons who know the business side of the application — the contextual, real-life angle of how users would actually use the application.

However, none of these groups is writing the user documentation. Instead, I am. I happen to be writing all of it, too. If I am lucky, one of the SMEs will briefly review the user help before it’s published to the users. But to think that I can suck in all the knowledge that is floating around in the minds of the project team, and compile/arrange/present that without dedicating almost all my time as a field reporter, is just naive.

Read the rest of this entry »