Documentation 2.0

Raise your hand: who's heard of Web 2.0? This is the phenomenon that spawned sites like Google, flickr, del.icio.us, Wikipedia, Myspace, and many other "killer apps" for today's Internet. Even Web stalwarts like eBay, Amazon, and Slashdot predicted Web 2.0 long before it existed by making user comments crucial to the site's operation.

There are several discussions as to what Web 2.0 actually is, but the consensus seems to be that Web 2.0 consists of sites that a) run more like applications and b) contain content that is largely defined by users.

Think about Google. How does it provide all the content that it searches? It doesn't; a globe full of Internet users provide the content. And yet Google has stock worth like $380 a share. It provides none of the content; only mechanisms for searching and organizing that content. The same goes for Wikipedia. It falls on the Wikipedia users to provide all the content for the site. Without users, the site is useless. Same with flickr and del.icio.us. Collaboration is the key.

I write about this phenomenon for a couple reasons, but I share it on this blog because Microsoft released their own wiki on MSDN last week. The wiki consists of documentation for Visual Studio and .NET products. Each page is written by Microsoft's technical writers, but because this is a wiki, users can add their own comments to each page.

I really like this idea. I imagine that LabVIEW users know way more about how LV works than the technical writers do. That' s not a slight against my co-workers; rather, it's a recognition of the fact that we are limited by company resources and time. Users, on the other hand, play with a single LabVIEW version for years, while we have to move on the next project once the current one is finished. Not to mention that users actually use LabVIEW. Sure, there are one or two tech writers who can handle G programming, and we all take the LabVIEW Basics courses that NI offers. We use several VIs to help us with our numerous documentation processes. But our focus is on writing, not programming. I'm pretty sure that none of us have developed a test & measurement application.

Imagine if you opened up a user manual and noticed an error in the documentation. Or you notice that, based on your own experience with the product, a key piece of information is missing. If you're dilligent, you send feedback to NI, and a year or so later, you see the corrected material in the new version of the user manual.

Now rewind and imagine opening up that user manual and noticing the error. You log on to your account at ni.com and locate the topic in question (which has been posted online in HTML form). You click the Comment button and post a quick note that details the problem with the topic.

Two days later you receive an RSS notification saying that someone has replied to your comment. It turns out a small engineering company in the Midwest was using the same product incorrectly because the user manual is insufficient or erroneous. But, thanks to your correction, they went in a different direction and the project is moving ahead full steam. Over the next couple days you get several more replies from other users. Some ask questions about your post, and you reply. Some post scenarios where you have to do things differently than the manual describes. Others point out inaccuracies that you yourself had not noticed. A developer explains why certain quirks are present and announces that he's filed a request to change the behavior.

A year later, all pertinent information has been incorporated into the next version of the user manual, and even more people benefit. You gain self-satisfaction and a reputation as a trustworthy expert who knows the inner workings of LabVIEW. Other users gain insight into how to use a particular feature. R&D, sales, and marketing folks gain evidence about how customers use their features. Marketing gains site traffic and credibility. (IT gains another server to handle the load.) Technical writers gain useful, valuable content that trickles down to other users who don't check ni.com. NI gains a positive reputation and tangible financial benefit.

All for nothing.

It could happen, right?

This is how I imagine documentation working, except I don't have to imagine it anymore. What Microsoft has done is create an open environment for users to collaborate based on shared experiences. Similar to Wikipedia, the initiative might expose flaws in their documentation, but I imagine the overall gains (as described above) far outstrip that small setback. They are embracing Web 2.0. And MS isn't alone. Other products have similar functionality for their documentation.

NI has already launched community.ni.com which is a effort to leap into Web 2.0. On this site, users can submit VIs, comment on them, trade tips about them, rate them, and otherwise collaborate. I envision something happening for LabVIEW and other NI documentation.