WikiWiki as Tech Review Vehicle


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 (22)

  1. WikiWiki as Tech Review Vehicle I know of some tech writers who’ve used wikis with some measure of success for…

  2. Ben Dover says:

    Why not convert MSDN to a Wiki, that should be interesting 😀

  3. Yeah, I’ve used a wiki for a couple of projects now to share information, both with my team and the sponsors and it has worked really well.

    In a reply to a comment on Jim Griesmer’s blog, he said that "In Visual Studio we have moved many of our functional specs to a wiki rather than keeping them as Word documents."

    http://blogs.msdn.com/jimgries/archive/2004/02/14/72914.aspx#FeedBack

    Also now Ward Cunningham (Wiki inventor) works at Microsoft, maybe we can expect more in later Sharepoint releases?

    Wrote up some additions we made to Open Wiki (ASP implementation) here:

    http://www.codeproject.com/useritems/wiki.asp

    Going to look at maybe moving to FlexiWiki as better fit now with our .net development.

  4. Alex Dong says:

    Wouldn’t it be better if we could replace Wiki’s presentation with Weblog’s HTML Editor?

    Wiki’s mixing presentation with content makes it hard to edit. So I wonder how you handle formats in the FlexWiki?

  5. Ben Dover says:

    A Wiki would be good for inter team documentation but Wiki’s depend on one thing, trust.

  6. Steve says:

    That would be my primary concern – Wiki vandalism.

  7. Tom Slee says:

    I’m with a group at Sybase that has just started using a wiki for technical review. We are using it more as a usability review (carry out this task, tell us where we screwed up) than as a proof-reading tool.

    One question: do you actually load your docs up into the wiki? If so, how?

  8. Good question. I author in Word and publish to both compiled help files (HTML Help 2.0 .hxs file) and to MSDN as html pages. During the doc build process, we transform WordML into simple XML.

    When I want to send one of my help topics to tech review, I grab its mid-build xml and transform it into WikiText. Since my XML input is so simple and WikiText (at least as implemented by FlexWiki) is so simple, the XSL file is simple as well. As wikis get closer and closer to the ideal (modeless editing, WYSIWYG, fancy presentation), the transform will become increasingly complex.

    FlexWiki offers a behavior whose syntax is @@XmlTransform("http://servername/mysource.xml", "http://servername/myxsl.xsl")@@

    that DYNAMICALLY transforms xml source files into WikiText on the fly.

  9. Tom Slee says:

    Thanks for the response — we write in XML and some kind of X2Wiki transformation should not be difficult. I may well give this a try.

    Is there anything you can do to get rid of the juvenile spam in this space?

  10. Persone los pioneros non rabata. Great…

  11. Wikis are gaining more attention as a collaborative tool for sharing and updating information. Most people…

  12. Poll Pitt says:

    I am so [url=http://access.2surf.eu]lucky[/url] on having what I have! And good luck in yours [url=http://2access.2surf.eu]search[/url].

    Just visit [url=http://access.122mb.com]my site[/url].

  13. Thank you for this great post about <a href="http://cashback.50megs.com/bad-credit-refinance.html"”>http://cashback.50megs.com/bad-credit-refinance.html" title="bad credit refinance">bad credit refinance</a> and [URL=http://cashback.50megs.com/bad-credit-refinance.html]bad credit refinance[/URL]

  14. Very interesting and good point about <a href="http://horseracing.builtfree.org/buying-car-new.html"”>http://horseracing.builtfree.org/buying-car-new.html" title="buying car new">buying car new</a> and [URL=http://horseracing.builtfree.org/buying-car-new.html]buying car new[/URL]

Skip to main content