Core Dump

Sarah Maddox has published an article about using wikis in technical communication, based on her experience as a writer with Atlassian, the developers of the Confluence wiki. As a bonus, when you download the PDF you get another article about trends in British technical communication.

Labels: technical communication, wikis

The always insightful Tom Johnson has been using a wiki to document a project, and he's written about some of the lessons learned. His experience parallels mine at work. If you're using a wiki, or planning to, read this article.

You have to think carefully about the navigation

The best-practice paradigm of topic-based authoring — authoring content in small chunks that you can manipulate and single source — doesn’t seem to apply to wikis. If you chunk each section as its own page, readers will bounce from page to page to page. It will become a dizzying experience of clicking and clicking.

Perhaps there’s a way to pull in sections from other pages, but I don’t know how to do that yet. Maybe wikis break down when it comes to single sourcing for multiple roles or audiences. Not sure here.

Depending on the wiki you are using and the web server it runs on, you may be able to include text from other pages in a wiki page - we use PHP include statements to do this - it works similar to the way text insets for in FrameMaker.

Labels: technical communication, wikis

We've been using a wiki at work for more than a year, and it's gradually getting adopted more widely across the organization. I have to admit that I have mixed feelings about this - it's good that people are making more documentation available, but a wiki isn't necessarily the best platform for some types of documentation, especially when you want to reuse or repurpose some of the information.

While it's pretty easy to get information into a wiki (we have a decent Word macro, for example), getting information out and into other formats is another matter. I tend to think of a wiki as something like a black hole - information goes in but doesn't come back out (other than by Hawking radiation, anyway, randomly and one quanta at a time).

Sarah Maddox has done us all a service by compiling a detailed list of tools for converting information to and from wiki format. If you have a corporate wiki, this is going to be an essential resource.

For the past couple of months I’ve been writing myself notes whenever I see mention of such a tool. Now I’ve added a bit of web searching to the mix. Here’s the resulting motley collection of tools that convert to/from wikis to/from wherever/whatever. It’s by no means complete, its order is decidedly random, and it focuses on Confluence and MediaWiki more than on other wikis, because Confluence is the wiki I use and MediaWiki is a biggie. If you know of other tools not mentioned here, I’d love it if you add a comment to this post.

Labels: technical communication, wikis

Last night, I went to a Toronto Wiki Tuesday meetup to hear my co-worker, Scott Nesbitt, give a presentation, Thinking About the Book, about using wikis for documentation. About 20 people were on hand, hanging off Scott's every word, and treating him to rounds of rapturous applause and many rounds of beer after (well, I'm not sure about the last, because I left before he did).

Scott knows much more about wikis than I do - he's the person who introduced me to them, and his presentation covers a lot of ground. You can view it, along with the slide notes, which you will need, on his company's web site.

There was a lot of interaction with the audience during the presentation - I actually found it a little annoying at times - but it was nice to see an engaged audience and Scott handled it well. As far as I could tell, most of the audience weren't technical writers, and some weren't very familiar with wikis.

I'll probably go back for more meetings. The Groundhog Pub (Sherbourne and Bloor) is a congenial place too - the downstairs meeting room is ideal for this type of meeting and they have a reasonable selection of beer and pub food.

Labels: technical communication, wikis

My co-worker, Scott Nesbitt, will be giving a presentation called "Thinking Outside the Book" at Toronto Wiki Tuesdays, tommorrow evening, September 8th. Details here. Scott has been making extensive use of our wiki at work, and it should be an interesting presentation.

In this talk, Scott Nesbitt will explore the constantly evolving role of wikis in the creation and distribution of documentation. Drawing on a number of real-world example, Scott will discuss:

* The benefits of using wikis for documentation
* How both Open Source projects and firms of varying sizes use wikis to deliver documentation
* The technologies used to get content into and out of wikis
* The pros and cons of involving your community of users in the documentation process
* When a wiki might not be the best choice for delivering documentation

I plan on attending and will likely post a report here.

Labels: technical communication, wikis

The U.S. Army has started a program to convert its field manuals to wiki format, in the hopes that soldiers will use their battlefield experience to improve them. This makes a lot of sense, especially as the "up or out" program has resulted in a lot of experienced soldiers being forced out because they weren't suitable for promotion.

Yet the Army seems willing to accept some loss of control. Under the three-month pilot program, the current version of each guide can be edited by anyone around the world who has been issued the ID card that allows access to the Army Internet system. About 200 other highly practical field manuals that will be renamed Army Tactics, Techniques and Procedures, or A.T.T.P., will be candidates for wikification.

As is true with Wikipedia, those changes will appear immediately on the site, though there is a team assigned to each manual to review new edits. Unlike Wikipedia, however, there will be no anonymous contributors.

Labels: technical communication, wikis

Thanks to Scott Nesbitt for pointing out Wiki1001, a directory of hundreds of wikis The home page lists popular wikis, like Wikipedia and WikiHow, and you can page through the directory from there, as well as search it. A grouping by category would be helpful though.

Labels: wikis

Tom Johnson looks at the help for Google's new Google Voice service and finds that it could be better.

Google puts a lot of effort in the overview video. That’s a smart move. When people want to learn about Google Voice, the overview video communicates the service in a catchy way, with more of Google’s branding. This video is probably watched thousands of times (a lot more than any other video), so it makes sense to go to the effort of including animation.

What I don’t like about Google’s help is the lack of integration between the video and help content. Not every topic deserves a video. Many times I’d rather read the help. And sometimes I’d rather watch a video. Separating the two formats so strongly is a poor usability move. The forum and blog also need to be more closely integrated with the other help materials.

Labels: usability, wikis

Sarah Maddox has another interesting post from the Australian Online Documentation and Content Conference - this one about a presentation she gave called Delivering Documentation on a Wiki. She's a technical writer at Atlassian, the makers of the Confluence wiki, so she has a pretty good grasp of the subject. Her presentation covers the following areas:

* How a wiki is useful in agile development.
* Workflow and tracking.
* How to put some structure into wiki documentation.
* Release management.
* Steering wiki development — how we as technical writers can let wiki developers and plugin developers know what features we’d like in a wiki.

As I've found out, using a wiki for documentation can be challenging. It's easy to get information into a wiki - not so easy to share it with other documentation tools. And converting your docs to wiki format and expecting someone else to update them probably won't work. She discusses some of these issues in her presentation in the section "Steering the Wiki".

Labels: technical communication, wikis

If you want to learn about using a wiki, Atlassian is offering a ridiculously good deal right now. You can get a 5-user license of Confluence, widely regarded as one of the best wikis for documentation, for $5. The offer is good for the next 5 days.

This isn't toy software - you'll need to install a database and application server to run it. But if you want to learn about wikis, you could do a lot worse.

Update: More details on ffeathers. I should have noted that the proceeds go to the charity Room to Read. Also there are a limited number of licenses available. He's posted a link to an article that explains how to install it easily on Amazon's cloud servers, and it looks pretty straightforward.

Labels: wikis

The stand-alone version of Mylyn WikiText is available for download. I had a quick look a the documentation for this and it looks like it should allow the exchange of DITA content between Confluence and MediaWiki and a couple of other formats. You will need some familiarity with Ant to run build scripts on the included .jar files.

I'm going to have to keep an eye on this - it looks like it may offer a solution for getting text out of our TWiki wiki at work, although we'd have to develop a structured FrameMaker DITA template to go with it.

Labels: DITA, technical communication, wikis

There's yet another attempt to add DITA support to wikis. Mylyn WikiText now can output DITA from wiki markup.

Mylyn WikiText provides a flexible architecture supporting multiple wiki markup languages. This provides organizations with many options when considering a DITA toolchain, whether it be a one-time conversion of existing wiki assets to DITA, or as an integrated part of a publishing process. Currently supported are MediaWiki, Textile, Confluence, TWiki and TracWiki.

I might have to take a look at this. It would be nice to be able to take TWiki markup and bring it into structured FrameMaker as DITA-formatted content.

Labels: DITA, wikis

FLOSS Manuals is a wiki-based tool for creating documentation. It's intended for use with open source projects, but it could easily be used for other things. Janet Swisher has a review on her site.

Flossmanuals.net is based on TWiki, and uses the Xinha WYSIWYG editor for HTML. Because it is a wiki, anyone can create a chapter or a manual, and anyone can edit an existing chapter. However, the maintainer of a manual has control over what changes are ultimately published. I've generally been skeptical of wiki advocates who say, “Oh yeah, and you can create documentation in a wiki, too”, because I've seen very few actual examples. (I've heard that the STC Austin chapter is going to have a presentation about this from someone at Sun, which I'm looking forward to. There's also a group devoted to Wikis for technical documentation at The Content Wrangler Community on Ning.) What's different about the FLOSS Manuals wiki is that it is purpose-built for creating documentation. It's not a case of taking a generic wiki and trying to magically extract documentation from it.

However, a manual on FLOSS Manuals doesn't just live on the wiki. You can take a manual (or a set of chapters selected for your needs), and publish it to HTML or PDF. You can host it on your website, or ship it with your application. You can even “self-publish” it for print-on-demand hard copies through lulu.com. FLOSS Manuals has published a manual for Audacity (audio editing software) this way, and the XO and Sugar manuals will also be available through print-on-demand.

Charles Jeter also writes about it on his blog.

FLOSSManuals.net is a great place to start writing content for developers if you’re just starting out or would like to support a friend’s really cool application. I know of several for-profit companies that put out free widgets of one sort or another that don’t have tech writing staff. This would be perfect for that as well.

The other side of the coin is that it gives a good measure of what’s actually effective. While wiki implementation is challenging, on a cost scale when someone like FLOSSManuals is administrating it, it’s definitely worth exploring.

Labels: software, wikis

Although Wikipedia is probably the best known and most successful example of a wiki, it has been controversial, and sometimes that gets used as a reason why wikis aren't appropriate for corporate use. Wiki evangelist Stewart Mader examines the differences between internet wikis, like Wikipedia and enterprise wikis.

• Spaces
• Security
• Integration
• Typical uses
• Contribution level

Labels: software, technical communication, wikis