Wikis For The Win!

When the VDI 3 team decided that all the documentation for our new product would be done on, I really didn't give it a lot of thought.  I'm a huge believer in and consumer of social media from blogs to twitter and I know the power they can have if used correctly. 

After we released the product there was a lot of negative feedback on the documentation for a variety of reasons such as no access to the internet, not portable, etc.  While those are valid concerns, I believe the primary reason for the negative feedback boiled down having to navigate something new.  But honestly I was starting to have my doubts as some customers weren't happy at all.  Maybe the world wasn't ready for wiki only documentation for a Sun product.

The VDI 3 team made the docs available in a PDF (Release notes included).  However the purpose of this entry isn't about changing to PDF, it's about the real benefit of the Wiki format for documentation.  Not to take anything away from the old documentation process, but in all fairness it is a slow process.  Now consider this.

Recently we added support for Solaris 10 U7 with our first patch for VDI 3, this allows one to use a S10 U7 Server instead of OpenSolaris for the iSCSI/ZFS storage magic that is a huge part of Sun VDI 3.  This morning a Systems Engineer asked this question:

Is somebody preparing instruction for Solaris10 Storage Server?

Within a couple of hours, this response came back:

I've added


I could rattle off more 100 examples like that one for topics like clarification, errors, missing info, etc.  Changes that used to take days, weeks, or months to make its way into the official documentation and out to the user base is now done in minutes.  The response time is a credit to our great VDI engineering team, the agility is due to the wiki and the combination is a win, plain and simple.  Many thanks to the Sun VDI team and the Sun Community Services Engineering team.


Frankly, this looks more like a win for having a product wiki than for producing all of your documentation on a wiki. There's no reason why you can't produce professional product documentation for your customers that is portable, printable, searchable, consistent, formatted, and indexed and \*also\* post the latest product information on your product wiki. You could just incorporate the posted information later in the next release of the more formal product documentation.

Posted by JaniceG on June 17, 2009 at 07:15 AM PDT #

I could not agree more with Janice's comments.

I would also add that in my experience, much of the apparent slowness of using the traditional methods for publishing documentation is the result of the need to have my content validated before publication.

On a wiki, saving equals publication. And while this model does offer the frisson of instant gratification, I can't help wondering if it is achieved by eliminating the content validation step or, more probably, delegating that step to the first customer to use the updated information.

I also notice that the VDI 3 team made the documentation available in PDF, presumably in response to customer demand. One of the most frequent complaints I hear from customers whose production documentation has been migrated to a wiki is the lack of high quality PDF.

The use of wikis for product documentation has other drawbacks too. Translations of information in a wiki are much more difficult and expensive than translations of information in the structured format that we use in our traditional publication processes.

I could probably rattle off many more examples of the drawbacks of using wikis for product documentation. These drawbacks are a result of deferring to opinionated nonexperts. They see only one aspect of the problem, and are unaware of the knock-on effects of their imposed solution.

Posted by Paul Davies on June 17, 2009 at 08:43 AM PDT #

Wonder if the same backlash was felt by printing companies when the docs that were physical started going PDF. Times change. Professionally done Wiki's are where tech writing is going.

Posted by Thin Guy on June 19, 2009 at 12:53 AM PDT #

ThinGuy, many thanks for props! It's one of Sun's fastest growing community sites & tech writers creating documentation comprise most of our power users.

Hi Janice & Paul, +1 to the notion that no single tool meets all needs w/o compromise. Some of the documentation system gaps have or will be added to, but there's no intent to extend our wiki tool to be something it's not (translation tools, documentation or content mgt systems, etc.). The nice thing about the use of tools and process is in most cases, it doesn't have to be all or nothing, but that's up to the team to decide which combo best meets the needs -- it sounds like you guys have some well-though-out ideas.

Happy to chat further if you'd like. I'll be at part of the Wiki Use Summit in MPK next week. Not sure who was invited to that -- I'm just an invited speaker. :-)

Posted by Skrocki on June 19, 2009 at 03:22 AM PDT #

"Professionally done Wiki's are where tech writing is going."

I wouldn't count on this - many organizations are experiencing similar issues to the ones I mentioned earlier. I think it's fair to say that many technical communicators are using wikis to inform their product documentation but I haven't seen any evidence of a wave of companies putting their documentation completely in wikis.

Posted by JaniceG on June 20, 2009 at 01:12 PM PDT #

What's with the negativity? Why not embrace a new tool. It's not the medium that matters as much as the words. If the words can get out quicker and perhaps with some new insight why is that so bad? I work in a field that we are constantly replacing old thoughts with new so to me the defending of the old with just a "I don't think so" defense is pretty weak.


Posted by Thin Guy on June 21, 2009 at 01:35 PM PDT #

Since I had a role in some of the particular documentation under discussion here (Sun Ray Server Software, Sun Ray Connector for Windows OS, the first VDI release, etc.), I'd like to add my $0.02 to this discussion.

First, the second paragraph of the original post mentions some important customer concerns ("negative feedback") about the Wiki-based VDI documentation, such as lack of portability and lack of web access, that are not addressed elsewhere but, IMO, need to be. It might be interesting to compare customer/field response to the first version of the VDI documentation, on, to the Wiki version.)

Second, I favor some tools over others for ease of use and power as well as familiarity. However, when considering product documentation -- as opposed to product management sites, blogs, or online encyclopedias -- it's the customers' ease of use we ought to keep in mind. That's why, for instance, I have never been a big fan of HTML or SGML but do like PDF: Properly generated documents look like books (OK, virtual books, if you like), and have multiple entry and search methods. I say "properly generated" because the Wiki-generated PDF output looks primitive compared to what's on, lacking, in addition to proper formatting, key elements such as publication dates, part numbers, and revision numbers.

Third, changes to product documentation should be verified. When I get inquiries or potential corrections -- usually from a product-related technical alias, occasionally through "official" channels -- I verify the content with senior staff engineers. Well-intentioned but technically incorrect "solutions" often appear on the aliases; it does not help customers to let these slip into the documentation. If there's an important change or, to be frank, an embarrassing typo, I'll re-publish the doc in question on It typically takes a couple of hours to button-hole a developer and verify an answer, five or ten minutes to correct the text, and a day or two to republish. This is a vast improvement over the old days when no corrections could be made once final copy was sent to the commercial printer. Allowing (potentially wrong) corrections instantaneously doesn't seem to me to be an advantage over re-publishing PDF or HTML when there's sufficient cause.

Posted by Gary Sloane on June 23, 2009 at 09:03 AM PDT #

As long as it's not to the detriment of

I'm a comparatively recent convert to Sun software products, and I have to say Sun's product documentation is simply fabulous. It's beautifully written, comprehensive, centralised (i.e. I can find everything I need in one place)...everything the mess of Linux documentation isn't. It would be a real shame to see a shift in direction on this one for the worst.

Posted by Dave on June 28, 2009 at 09:52 AM PDT #

"While those are valid concerns, I believe the primary reason for the negative feedback boiled down having to navigate something new. "

Rubbish. That post does your wonderful blog a great disservice.

Moving to wiki-only docs to cut costs is bogus if you don't know who your customers are or why they \*choose\* to pay for your product.

If some customers want to contribute to a wiki that complements the normal docs, that's great. The wiki is upside; part of the community building process. IMO most paying customers want a well-finished-enough product (including documentation) to achieve their business goals rather than aspiring to be part of the development process.

Do not dismiss "no access to the internet, not portable" as objections when you don't know who your customers are or where they are or the conditions they work under.

Posted by Michael Bukva on July 02, 2009 at 11:16 AM PDT #

Wow Michael. Rubbish? The complaints I spoke of were coming mostly from people complaining they couldn't find something which I'd then point them to the exact entry on the wiki. 95% of the time they shrug it off to not understanding how a wiki work. Do you really think the search on is better? It's not. And we fixed the not portable, have you see the latest Confluence PDF generator? Flows nicely. Also, since we don't ship doc anymore at least one time you'd need access to the internet.

Kind of hurts to think that people think I don't know our customers when I spend about 95% of my time listening to them. Guess I'm doing a poor job.

Let me be clear, this isn't a community driven doc effort, i.e. we aren't throwing software out there and having the users put the doc up. We have professional doc writers putting the content on the wiki on behalf the engineering staff and the testing done by QA. Updates are extremely frequent based on questions/concerns from the field.

Posted by Thin Guy on July 02, 2009 at 04:03 PM PDT #

ThinGuy knows who our customers are and the conditions they work under much better than most people.

Posted by Gary Sloane on July 02, 2009 at 04:36 PM PDT #


Please accept my sincere apologies for the tone and personal nature of the negative comments in my previous post. It is way way out of line of me to question your efforts on behalf of customers. Whatever I think about how some stuff is documented, that post wasn't the right way to get anything done about it.

Posted by Michael Bukva on July 05, 2009 at 05:07 PM PDT #

There have been a lot of comments about how wikis can't produce "professional" looking PDFs or how wikis will generate information with more errors.

The first point may be valid now, but it's not going to be like that forever. People need to remember that wikis are still relatively new and advances are happening every day.

As for the lack of validity in wikis, it depends on how it is maintained and if you have people dedicated to the accuracy of the information. I can maintain and validate information on just as easily as if I used a standard publication system, and why shouldn't those "senior staff engineers" be able to update the information directly? They are the experts.

The bottom line is that all the "problems" with wikis are totally outweighed (in my opinion) by the openness and sharing of information. Lowering the barrier, even with an internal engineering team, will ultimately make the information better. And, with "agile" engineering and lean writing teams, the more help the better.

Wikis don't replace the need for good writers, but they do enable the experts to be able to contribute more easily and make the product documentation "owned" by the team. To me, that's what is important.


Posted by Paul Kasper on July 07, 2009 at 07:08 AM PDT #

Post a Comment:
Comments are closed for this entry.

Think Thin is a collection of bloggers that work with Oracle's Virtual Desktop portfolio of products.


« July 2016