Partager via

WikiWiki as Tech Review Vehicle

  • Article

Like most technical writers, getting my feature team to review my help topics for technical accuracy is like keeping an Iditarod team from making a dash for the nearest McDonalds or garbage dump in the middle of a blinding blizzard.  Technical contributors want to participate in technical documentation reviews but they rarely have enough bandwidth to do so effectively. Consequently, I spend a lot of time trying to determine the most effective way to squeeze my teammates for feedback.  This can be a painstaking process, especially for technical writers who are unlucky enough to work with teams that are halfway around the world or spread across the country. Some contributors only produce if I corner them in their office with a paper copy.  Others are overly motivated, but I love them all the same.  Most technical reviewers, at least at Microsoft, require a combination of:  incentives (food, beer, ...), attention getters (a stern note from their manager) and tech review tools that fit their working style and team culture.

 

At various times in Microsoft's history, user education/assistance teams have developed one-off tech review tools whose capabilities transcend the standard commenting, reviewing, and change tracking features in Microsoft Word.  Like everything at Microsoft, our internal tools have codenames.  I once used a tool called Slingshot, which was developed by one of the programmer/writers on the Visual Studio SDK team back in the good old days of HTML 1.x.  Slingshot was a WYSIWYG collaborative comment collector for compiled help files (CHMs).  It worked great.  Unfortunately, Slingshot is outdated, for a variety of reasons.

 

Thus, for the last three years, I've used WinWord (or hard copies) to collect tech review feedback from my team. I experimented briefly with Microsoft Reader a few years ago, an effort that met with as much success as eBooks.  More recently, I've been preparing to use SharePoint in the run up to our next release of Visual Studio.  SharePoint transforms Word into a truly interactive collaborative development environment.

 

And then there was WikiWiki.

 

Last week, on a whim, I decided to publish a small, eight-topic tech review to my internal wiki.  Developers dig Wiki.  It's just close enough to the metal to spark their interest. Here are a few of the reasons that I think Wiki (FlexWiki in particular) is well-positioned to become the tech review tool of choice for technical writers in the 21st century:

 

0) Change Tracking: version by version, user by user with timestamps, the ability to view and/or rollback to a particular version, and edit highlighting.

1) FlexWiki provides namespace change notifications via an RSS feed (like blogs). At 9:25AM this morning, my newsreader notified me via Outlook style popup that a team member had changed my SourceControlConcepts page at 9:20AM. I promptly incorporated his changes into the master copy of my docs.

2) TOC  Ryan LaNeve, a non-Microsoftie, has created a "WikiBehavior" that dynamically displays all of the topics in a FlexWiki namespace, hierarchically inside a wiki topic.  Think Table Of Contents.

3) Filtering:  another "WikiBehavior" allows a Wiki namespace editor to mark pages as {Property: NeedsReview}.

4) FlexWiki supports Topic Includes... (essentially, a topic collage) and image includes.

5) Comments (well, sorta). The existing TopicTips feature could probably be adapted to this use with a few lines of code.

6) It's FREE.

7) It's EXTENSIBLE. FlexWiki is written in C# and can be easily, easily altered and improved using Microsoft Visual Studio .NET's rapid application development tools.

8) FlexWiki supports Parallel Development: multiple individuals can edit the same topic simultaneously.

 

Are you a writer?  To voice your views on the potential of Wiki as a tech review medium, leave a blog comment.

Comments