What do you think about using a wiki for technical documentation?

I've been a technical writer for more than ten years, and have used the full range of tools. About four years ago, I started a new job. Whee, all the documentation is on a wiki! I loved it from the start. It was an entirely new experience.

Technically, I had to learn the new tool, which is always exciting. But there was even more to get my head around. Publishing updates that are immediately visible to the whole wide world, unless I hide them. (Heh, I guess you could truly say, "Publish and be damned.") People dropping in on a page directly from Google, with no prior context. The entire company updating the documents as and when required. Customers adding comments to the pages. And even... customers and community authors updating the pages.

We're using Confluence wiki. Fair disclosure: The company I work for, Atlassian, is also the company that develops Confluence. There are a number of other wiki brands out there, such as MediaWiki (that's the wiki used by Wikipedia), PBWiki (now PBworkds), DokuWiki, MindTouch (was deki wiki) and more.

So I'm wondering how many people are using a wiki for technical documentation, or are considering one. What do you think about the whole idea, the "challenges" ;) and the advantages?

Tags: wiki

Views: 14717

Reply to This

Replies to This Discussion

Richard -- Various departments at my company (a small one - about 60 people) have been putting various internal technical documents on our company Wiki (using MediaWiki).  During the past month approximately, I've been working on various customer service procedures, getting input in various forms from the technical analysts, editing and re-formatting it in Word, and then using a Word-to-MediaWiki Conversion Tool (Microsoft's) to get it into MediaWiki syntax.  I have to then "tweak" it a bit after that in MediaWiki, but so far it seems to be working well. This is my first experience working with a Wiki.

Melanie

Hi Melanie,

I've also used various Word-to-Mediawiki tools but found that they all had different areas that didn't work. I ended up creating a new version using bits from other tools and also added a feature I need to handle tables with merged cells.

It is freeware (as I copied a proportion of it from other people) so let me know if your Microsoft version isn't sufficient.

Gareth

We're looking at a Wiki as a tool for collaborating and communicating with our customers. We want to make our content assets searchable - a Wiki might serve this purpose. Currently, we publish from an XML-based CMS to PDF and do not intend the Wiki to be our development platform. Our hurdle now is to convert our XML to Wiki.... Thanks, Sarah, for starting this topic. It's early days for us.

XML to Wiki shouln't be hard, certainly no harder than PDF, but before you make that jump, consider whether a wiki is a help or a hindrance. I don't know anything about your setup or your needs, but I do wonder what benefits a wiki actually affords you if you aren't authoring in it. I'm sure you know the origin of the name "wiki." Hawaiian (wiki wiki) meaning quick. That's really the main advantage of a wiki, that everyone (you give permission to) can easily and quickly edit it in-place. If you aren't going to be authoring or maintaining docs in the wiki, then it would seem to add complexity and limitations. 

If I were editing in XML and wanting to get content on the web, I'd publish to HTML instead of wiki. That way you skip the extra (and wholly un-necessary) translation step where the wiki platform converts the wiki markup back to HTML. Also, HTML and CSS2.1 afford you a massively improved markup language relative to wiki text. Compared to current HTML, JS, and CSS, wiki text is like working in a subset of HTML back in 1995. :-)  

In other words: 

a) XML --(transform to wiki)--> Wiki text --(wiki converts to)--> HTML 

b) XML --(transform to HTML)--> HTML

Richard, you are quite right. We want a searchable, highly usable content solution for our customers and we also want to give our customers an opportunity to interact with us and provide comments. But we aren't ready to jettison our CMS just yet :) We can extract to HTML, but have encountered some publishing issues.

Hallo Tamsin

One way to use the wiki would be to allow your customers to add comments to the documentation pages. You could even allow them to create and update pages in part of the wiki, while configuring other parts to be view-only for customers.

Usually, there are two main ways the community can contribute to the wiki. One is by commenting on the wiki pages. The other is by creating and updating pages.

If your wiki is Confluence, the way to do it is using Confluence "spaces" and the Confluence permissions scheme to separate the "official" product documentation from the community-contributed documentation.

The product doc spaces could allow customers to comment on pages, but not add or update pages. This ensures that their contributions are not lost when you update the wiki from the XML source. The comments remain on the pages, but the page content is replaced with the content from the CMS.

The community spaces would be authored and maintained entirely on the wiki, by your own tech writers and the community and/or customers. We find it works really well for the tech writers to set up the structure of the space and to monitor the spaces (via watches or RSS feeds) to check that nothing goes awry. Our community authors are great at contributing good and useful content.

Is your CMS DITA-based? The WebWorks ePublisher tool does a good job of converting content from DITA to Confluence wiki, with fairly sophisticated styling and configuration options, batch processing and scheduling.

It's a good point that Richard makes, about converting from XML to wiki markup. As an FYI, Confluence is moving away from wiki markup towards storing all content in XHTML. That will make the conversion to and from XML even easier. :)

There's an open source tool for converting from DITA to wiki format, called DITA2wiki. It's a stand-alone tool that converts DITA XML documents to wiki format and uploads them into the wiki via a set of Ant commands.

Sarah, thanks for your thoughtful response. Indeed, we are interested in separating official product documentation from community-contributed content. This is very helpful and gives us much to think about and explore. I am sure this is not the end of this topic.

Hi Sarah,

Let me first say that I'm a fan of your blog and really appreciate your voice on the web. You always liven up a discussion.

As to your question about wiki documentation, I began writing for wikis when I was a contractor at the National Cancer Institute Center for Biomedical Informatics and Information Technology (NCICBIIT, how's that for a name?) from 2006 through early 2010. I worked primarily with the Enterprise Vocabulary Services (EVS) group, staffed by medical terminology specialists who developed the ontologies used in the NCI Thesaurus and Metathesaurus. I wrote documentation to support their work and to train new contractors. 

When I started at the NCI, we were using primarily FrameMaker and Quadralay ePublisher. I was the gatekeeper of the Frame templates. At some point, the EVS set up a wiki to encourage medical terminology experts to contribute to the development of a new terminology called BiomedGT. The wiki enabled users to search through the vocabulary and recommend changes using an online proposal submission process. The platform was MediaWiki, and the group asked me to reorganize the main pages and develop help content for users. During the process, I learned as much about MediaWiki as I could. I quickly adapted to the medium and found that it liberated me from focusing on tools and enabled me to focus more on content and organization. I wanted to set up standardized content for reuse, so I used what MediaWiki calls transclusion (basically referencing templates in a change-once/surface content approach).

At that same point, the NCICBIIT adopted Confluence as the official wiki platform for the entire organization. All of the project teams began to use Confluence for project documentation and collaboration. At the time, I was developing MadCap Flare templates for the center, so I started a Flare Knowledge Base on the Confluence wiki.

I'm no longer on the NCICBIIT contract, but I keep up with their activities. The Technical Writing team has now bypassed both FrameMaker and Flare (as far as I know) and have ported all of their documentation the Confluence wiki. I realize that I'm writing to an Atlassian employee, but I can say in all sincerity that I found Confluence robust and fun to use.

I believe that wikis are well suited to topic-based writing. They're great for collaboration and content reviews. They also provide mechanisms for content reuse. The initial challenge is learning the markup, which isn't difficult. At one point I was working on both MediaWiki and Confluence, and I had no trouble switching back and forth. (Well, maybe occasionally...) 

Cheers,

Eddie

Hallo Eddie,

Thank you for all that great information. Wow, you've packed a lot of experience into those times with NCICBIIT: ePublisher, FrameMaker, MediaWiki, Confluence and Flare! I envy you the experience with MediaWiki in particular. I've read up about transclusion and other extended functionality that MediaWiki provides, such as import/export for various formats. But it's not until you get down to using the features that you really know how they work and how well they work.

It sounds as if the NCICBIIT (I do love that acronym) community were keen to adopt the wiki. I know that some organisations have trouble with getting people to contribute content to the wiki, at least at first. Did the medical terminology specialists show a lot of enthusiasm for the wiki way of working, and did you have to encourage them at first?

Hi Sarah,

Sorry for my belated reply. I do value those years at NCICBIIT, and I miss the dynamic learning environment. I had great experiences there. Since my initial experience with MediaWiki, I have long intended to install a MediaWiki on my server and get to know it from the ground up. I just haven't had the time.

The internal terminology specialists embraced the idea of working with the wiki, but the ramp-up time was a bit slow. Wikis were just starting to catch on, and the engineers running the wiki were still figuring things out. They gave me permission to access the main style sheet, and I was able to tweak the site's appearance. I didn't make any major modifications; I made only slight changes and spacing adjustments.

Another interesting aspect (and somewhat of a complication) was that the team was soliciting participation from outside terminology experts, who had to submit credentials before being accepted as reviewers. Some of them were a bit scared off by using the wiki. Another internal team was using the wiki for a separate terminology project, and they were the testers for the proposal system for new terminology. Let's just say that they required a lot of guidance. ;-)

Hi Eddie, thanks for all this great info. It looks like you've already pioneered the path from traditional online help to wiki-based social documentation - now the rest of us have to catch up! Now, another question - some of our users need off-line help (they aren't always connected to the Internet) - can you output from Confluence to something like a .chm? 

Confluence can export to .doc or PDF. Confluence does PDF export in a way that permits you to export pages as PDFs or an arbitrary group of pages (up to the whole space) as a single PDF if you want. Confluence generates PDFs of each page on save, so generating a single PDF of the whole space doesn't tax the server very hard. It also allows you to customize PDF export stylesheets, so our PDF exports look like actual company branded docs, with copyright notices, title pages, page numbers, etc.  It's a pretty good setup. I know that a lot of other tools allow PDF export. It's a pretty common feature, but I don't have as much experience with this feature of other tools.

RSS

Sponsors

Become a sponsor

© 2014   Created by Arnold Burian.

Badges  |  Report an Issue  |  Terms of Service