Contributing to wikis as a technical writer

I’ve been researching an article for STC Intercom about wikis and technical documentation as discussed in my previous post. In about two years of my interest in the topic, I have only discovered a handful of examples of wikis used for end-user documentation for a technical product. And sometimes I even stretched the term “technical product” to include all of eBay. Heh.

If you’re also interested in wiki research, I have also been compiling bookmarks of blogs or websites that comment on wiki use on del.icio.us too at http://del.icio.us/annegentle/wiki.

Anyway, here’s a list of the ones I’ve found as good examples so far, but my criteria are loose and fast, such as recognizable products or geeky products. I’m sure there are more, and this list of the top 57 wikis based on popularity offers an even longer list.

But instead of soliciting more examples, I want to ask a few more questions myself. How many of these wikis would I use to get an answer to a question? Probably all of them. Now, how many wikis have I contributed to? How about you? If you haven’t ever contributed to a wiki, why not? If you have, tell us which one, and what motivated you to contribute?

10 Comments

  • avi
    July 5, 2007 - 4:34 pm | Permalink

    Wikis are great for producing large amounts of structured text from bottom up (that is, structure while you write).
    However, no wiki system offer a way to deliver the produced content as PDF/CHM, hence legacy writers (all of us?) find out that moving to wiki means forgetting everything we’re doing today.

  • July 6, 2007 - 3:02 pm | Permalink

    It’s interesting that you associate wikis with structure, because most people wouldn’t. What makes you think it’s structured? The input you have to enter in forms? Wikitext? I’m curious. I thought that mostly writers find that it’s a bit too freeing and unstructured.

    I did find that many writers are like you, saying, how do I get my preferred output formats from a wiki? The Confluence Wiki that Dee Elling mentioned in a comment here: http://talk.bmc.com/blogs/blog-gentle/anne-gentle/dita-wiki#comments has PDF export capability. See http://confluence.atlassian.com/display/DOC/Confluence+Documentation+Home.

    But you’re right, it doesn’t necessarily make sense to move legacy content to a wiki when other formats are serving the users well.

  • July 7, 2007 - 7:18 pm | Permalink

    Hi Anne

    As you know, we use MediaWiki inside BMC, and we use it pretty much strictly for technical documentation. This has several dimensions:

    1) The people that have the knowledge are not technical writers, but they are the keepers of the knowledge. The advantage of aWiki is that once knowledge is up in place, other can help with the technical aspects of the writing.

    2) Google has proven that content is useless unless you can find it. The advantage of a Wiki like MediaWiki (the one we use) is that behind the scenes all content is kept in MySQl. That means the search function is highly usable. Search results are highly relevant. And therefore usage increases of the resource. And in out case, more people want to contribute *because it just works* ™.

    3) The problem with some forms of traditional documentation is that they are in propritary formats where “tribal knowledge” is required to know where the useful content is.

  • July 7, 2007 - 7:25 pm | Permalink

    PS: The hard thing to deal with on a Wiki is the feeling that everyone has that they can contribute, that what they have to write is useful and relevant, and the biggie: Document ownership.

    On a Wiki, no one “owns” the content. That is what makes them work. But first one has to get past the idea that only the creator can update the document. It is a stubborn thought paradigm, but it is utterly critical to do it.

    Technical writers might, at least in a serial fashion, feel less of this than the average population: At the very least, ownership moves around as re-orgs and new assignements happen.

    For technical writing from non-writers, the feeling of territory is strong. There may also be an aspect of “I didn’t want to correct their mistakes because I did not want them to be mad at me” in there someplace.

    There is an unleveraged power here. Once the technical people get past this document ownership issue, if you can then put a technical writer into the mix…

  • July 9, 2007 - 5:35 am | Permalink

    By “Structured” I mean “reasonably searchable and linked”. That is, if I write a use-case based user guide, I would like my wiki to be able to link the tpoics the way a user guide does.
    Again, the problem could be with my legacy point of view, as “tagged” or “easily searchable” may replace “structured into a table of contents” and “indexed”.

  • September 1, 2007 - 8:36 am | Permalink

    I don’t contribute often to wikis, but I would if I had something valuable to add or if I had a business reason for doing so. That said, I use wikis often and find them very valuable, thanks to those who do contribute content.

    From my vantage point, it is important to note that many of the so-called “problems” with wikis are not problems with the wiki technology, but instead are problems with leadership and governance during this time of change.

    For instance, it is simply not true that anyone can edit a wiki — yet many believe so. Today’s second-generation wikis provide various levels of access control, so we can create different levels of editing permission and assign each user with appropriate permissions (some users will be able to edit, but their edits will not go live until a user with approval permissions approves the content). So, what’s the real problem?

    The problem I see as most important to recognize is that knowledge workers have yet to understand their place in the content management life cycle. And, they often have a surprising view of who “owns” the content. For instance, regardless of whether you are using a wiki or not, you likely don’t “own the content” you are creating, even if you are using MS Word and storing your files in a folder called “My Documents”. Your role is not one of artist (although many writers see themselves that way). Instead, you are part of a content manufacturing process, that, chances are, don’t work very efficiently, regardless of what software tools are employed. If efficiency and business value were at the center of our decision-making, we simply wouldn’t be in the situation we are today – struggling to admit our content has value and therefore should be managed as a business asset.

    I could certainly write a book about these issues, but suffice it to say that our primary obstacle is not the wiki. It’s the changes content creators must make in their attitudes and the way in which they work. Change is difficult for most, but not impossible. I think we are in the midst of a major shift in the way writers work. The tools we use will change and help us to become more efficient.

    It should be interesting to see what happens over the next few years. I see a wiki in my future. What about you?

  • Shannon Greywalker
    September 4, 2007 - 9:28 am | Permalink

    I have contributed to many wikis of the WikiMedia and Drupal variety. Some of those wikis comprise millions of users. Some of them have formal editorial oversight and formal written arbitration policies and some are completely free-for-all with no oversight whatsoever.

    I have witnessed some serious “revision wars” where matters of ownership and disagreements over correct content have occurred. I have also witnessed many well-meaning revisions by contributors who frankly have no business attempting to write content for a wiki, because they either cannot write well or because they are entirely incorrect. I have seen well-written, concise articles turned upside down by a single well-meaning contributer who thought they were improving the article but instead they were making it literally 500% longer and full of extraneous detail that had no place in the context being discussed in the original article.

    I have seen the corporate owners of a wiki absolutely refuse to get involved in editorial disputes, saying “you work it out amongst yourselves” and refusing to ban aggressive contributers who stubbornly put orginal bad content back when it is revised to be less bad.

    My view of wikis these days, especially when used in a corporate context, is that if the wiki does not have formal oversight mechanisms in place, the wiki is essentially corrupt, untrustworthy, and not worth my time as a user nor as a contributor. To be successful, a wiki must have the following attributes:

    * A formal written set of policies about ettiqutte and arbitration.
    * A formal arbitration committee who is given the time needed to perform arbitration duities.
    * Active moderators who will quickly ban problem contributors on the say-so of the arbitration committee (if they don’t actually give the arbitration committee such powers to begin with).

  • Shannon Greywalker
    September 4, 2007 - 9:43 am | Permalink

    I’d also like to point out that over time, wikis tend to evolve a rather harsh and ruthless zeitgeist. Many wikis include a disclaimer on their edit pages that essentially says “do not submit your contribution unless you are prepared to have it ruthlessly edited”.

    What tends to happen over time is that the regular community of “editors” (the people who feel some sense of ownership for the wiki content and who frequently contribute or revise articles) become quite harsh and abrasive. Talk pages become filled with tersh, harsh, abrasive language that often belittles contributers.

    As a result, wikis seem prone to developing an exclusive “in-crowd” who begin to shape the wiki for better or worse, and who drive away newcomer contributers who aren’t capable of fitting in with the zeitgeist.

  • September 6, 2007 - 8:46 am | Permalink

    Scott, I love the “content manufacturing process” description.

    Shannon and Scott both, I’m reminded of a visual image of a crowded, loud newsroom where the journalists are writing their stories under the pressure of hitting their deadlines and also pitching stories to the editor for inclusion, and the jostling for the front page story. While that’s an old media description, its useful for describing the evolution that Shannon has witnessed. Unfortunately the wiki community can’t fire the editor or editors like a newspaper could.

    You’ve both hit on a crucial aspect of wikis – I believe the successful wikis are managed by an editor or editorial board who maintains the voice for all the submitted articles – much like a successful newspaper’s editor ensures their journalists’ submissions are keeping with the paper’s voice. However, the balancing act lies with the community’s success, not the editor’s, necessarily. Fascinating.

    Exciting times, these. Thanks so much for commenting.

  • Pingback: The Content Wrangler » Blog Archive » Anne Gentle vs JoAnn Hackos: Is There a Documentation Wiki In Your Future?

  • Leave a Reply