While researching my STC Intercom article about wikis and technical documentation to be published in a few months, I interviewed Dee Elling via phone and email because she left a helpful comment on my talk.bmc.com blog entry about a DITA and wiki combo. Dee’s the manager of the documentation group at CodeGear and she blogs at http://blogs.codegear.com/deeelling/.
Anne -What are some of the factors for selecting a wiki software package?
Dee -I’ve encountered hesitation from some writers about using a markup interface. Many writers preferred a Word-like GUI interface, such as Confluence provides. Another consideration is cost, since there is not always a budget for new systems; at CodeGear we use MediaWiki. Primarily we manage internal information such as schedules and doc plans; lately we are collaborating with engineers to write FAQs and release notes.
At my previous employer, one engineering team was writing the documentation themselves on the wiki (using outlines provided by the writer), and the writer cleaned it up and converted it to PDF for distribution with the product. That is a great use case which I believe could seed the adoption of wikis into the documentation process, especially in companies where there are limited doc resources.
At CodeGear I can post copyrighted material to our Developer Network. The Developer Network technology allows comments on postings, which is not the same as wiki but a good start. Since joining, I have started to post traditional doc content as “articles” there. I’ve already fixed a few doc issues due to rapid customer feedback! We are also working on a design to make the website interface more wiki-like.
Anne -How do you get legal approval for such an open-edit site?
Dee -At my previous company I never got to the stage of implementing a public wiki. However I had many discussions about the legal aspects elated to the product documentation. The legal aspects seem complex, but lawyers can write new terms for new situations.
At CodeGear the issue will involve intellectual property, but the user base is so active on the internet that there are few “secrets”. More important will be the issue of releasing information too soon or otherwise getting in trouble with SOX compliance. (That makes my head spin!)
Anne -What are the considerations when choosing where the wiki is hosted?
Dee -Cost and reliability are factors, but most important is buy-in from the IT department, who would likely manage the hosting.
Anne -Which types of products are best targeted for a wiki?
Dee -Complex software products are a good example. There is so much flexibility in software and product documentation cannot cover every use case. The wiki lets customers add content that is relevant to their own use cases, and that will benefit others.
Anne -How can you encourage your users to contribute?
Dee -Keeping up a dialog with the customers is helpful. If you respond to them, a dialog develops, and they are more likely to contribute again.
Anne -What are some of the success factors for the wikis that contain
technical documentation?
Dee -Does it result in more positive feedback from customers? Do customers help each other and contribute to strengthening the installed base? Does it increase product visibility and mindshare in the market? Is it perceived as a strategic advantage over competitors? Does it cut down on tech support phone calls?
Anne -What traps should be avoided?
Dee -The trap of not responding or not paying attention. Writers must diligently track the “living documents” they have created, and they must truly collaborate. If customers contribute and their contributions go unrecognized, they may think that the company is not fully supporting them.
Public wiki documentation must be actively managed and that takes more writer effort than in the past, when documents were forgotten as soon as they went to manufacturing. Contrary to the fear that with wikis you don’t need writers anymore, I believe that with wikis the role of the writer will grow.
Thanks so much for your help, Dee, and for sharing your experience with all of us who are interested in the best ways to harness the power of wikis for end-user doc.