Archive for the ‘wikis’ Category

Review of WIKI: Grow Your Own for Fun and Profit

Wednesday, December 15th, 2010

Over on the DMN Communications site, Scott Nesbitt has a review of Alan Porter’s new book, WIKI: Grow Your Own for Fun and Profit. Scott was the person who introduced me to wikis and helped me set up our space on the TMX wiki – he knows his stuff and the review is worth reading. The book looks like it is too.

The approach that Porter takes with WIKI: Grow Your Own for Fun and Profit is interesting. And it’s fun. Porter uses the metaphor of preparing and seeding a garden. And, if you think about it, a wiki is a lot like a garden. You need to do a lot of work up front before planting the seeds. Then, you need to nurture and maintain the garden.

All that work can be worthwhile when it comes time to harvest the information. And in 10 chapters Porter walks you through the phases that you need to go through in order to do that effectively.

He take you through each phase of planning, implementing, and maintaining a wiki. But with any software implementation, you need to do a lot up front. I recently read a tweet about Sharepoint that applies to wikis: the failure of an implementation has little to do with the software and just about everything to do with the way the software was implemented.

Though not stated as such in WIKI: Grow Your Own for Fun and Profit, this was (for me) one of the underlying lessons in the book.

Turning a wiki into a writing environment

Tuesday, August 17th, 2010

My (sadly now former) colleague, Scott Nesbitt, has been using a wiki to write for a while now. In this post, he explains how he customized DocuWiki to turn it into a personalized writing tool.

As I’ve chronicled elsewhere, I do a lot of writing with a wiki. In my case, DokuWiki. It’s not just an environment for me to work in (although that’s a big part of it). I’ve also used my wiki for collaborating with other writers.

I use wikis for planning, taking notes, and writing. Nothing else. To make those jobs more efficient, I needed to customize my instance of DokuWiki. That was fairly easy. The community supporting DokuWiki have created everything I need to do that job.

Moving from help authoring tools to web tools

Monday, June 7th, 2010

If you’ve been working in the technical communication field for as long as I have, you’ll have made the transition from writing for print to writing online help. Now there’s another transition happening – from online help to web-based documentation. Most likely, it’ll be in the form of wiki. Tom Johnson has a good article about this, concentrating on one of the main problems that writers have when faced with  working on a wiki, how to organize their content. ‘

Part of the problem with organizing content on wikis is lack of control. As soon as wikis become a collaborative effort, with multiple authors, the organization becomes much more challenging and is likely to suffer from inconsistency and chaos. I don’t know if this is inherent in collaborative authoring projects, or if it’s inherent in the wiki architecture, but eventually wikis become so disorganized that search becomes the only method of navigation.

Case in point, check out the WordPress Codex. If you have a body of information this size, there’s no clear way to organize it. You end up with links that you can kind of group together, into Getting Started, Design and Layout, Advanced Topics. But then you also have general groupings under vague topics like Working with WordPress and About WordPress. There’s no clear path through the content.

Writing in the Open reviewed

Wednesday, June 2nd, 2010

My colleague, Scott Nesbitt, has been working with wikis for quite a bit longer than I have. He introduced me to them after we found that one had magically appeared on the TSX intranet a couple of years ago. So it was with great interest that I read his review of a new book (booklet, really if you consider the length) from Sun Microsystems called Writing in the Open: Using Wikis to Create Documentation. If you’re using a wiki, or planning to, it sounds like the book should be worth reading, although it’s not an in-depth examination of the topic.

If you’re looking for a step-by-step guide to using wikis to create and deliver documentation, Writing in the Open isn’t it. It is, though an interesting and potentially useful set of best practices.

Using a wiki for technical communication

Tuesday, November 24th, 2009

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.

Lessons learned from using a wiki for documentation

Friday, October 30th, 2009

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.