Using Wikis as Project Documentation Tools

I was talking to Charles Arnold after the last STC-Suncoast chapter meeting about using wikis as project documentation tools. Neil Perlin just presented on Web 2.0, and referenced James Surowiecki’s The Wisdom of Crowds: Why the Many Are Smarter Than the Few and How Collective Wisdom Shapes Business, Economies, Societies and Nations. Surowiecki’s main idea is that collective wisdom almost always outstrips individual wisdom.

I was thinking about this today as I continued documenting our customized version of CRM, a client relationship management application from Microsoft. The IT team implementing it consists of about 30 people. Several SMEs know the product backwards and forwards. There’s a training department that is leading several sessions on it, and a support center with some sharp troubleshooters who also know the product well. Then there are business liaisons who know the business side of the application — the contextual, real-life angle of how users would actually use the application.

However, none of these groups is writing the user documentation. Instead, I am. I happen to be writing all of it, too. If I am lucky, one of the SMEs will briefly review the user help before it’s published to the users. But to think that I can suck in all the knowledge that is floating around in the minds of the project team, and compile/arrange/present that without dedicating almost all my time as a field reporter, is just naive.

The model of one writer or even several writers tackling all of the documentation is a model that will soon be history as Web 2.0 trends take over in technical communication. Wouldn’t it be so much cooler if we could have a wiki that I could work off of, and which everyone could read, review, edit, and even contribute towards? I could draw upon the collective intelligence of the entire project team, rather than just my own fiddlings and guesses with the program.

I was playing around with the SharePoint 2007 wiki features and also those of Socialtext. Here are the barriers I’m up against:

  • Wiki wysiwig’s are primitive (technical documentation can have some complicated styles, with several levels of lists).
  • Once all the info is in the wiki, how do I generate a manual or online help? I don’t want to maintain two separate files.

If you have any recommendations on wikis that have advanced WYSIWYG editors and allow you to customize the wiki code, let me know. Also, if you have actually worked on a project where a wiki was used, please tell me about it.

Several people today explained some of the drawbacks with wikis. Sure, the techies may inundate the wiki with irrelevant info; some of the info may be wrong and mislead users; some info may require more time reworking than if you had simply created it yourself. And so on. But c’mon, didn’t Wikipedia prove that a properly guided wiki can be enormously more powerful than static content written by a limited staff?

Also, I’m not proposing that you remove the technical writer and just encourage the project members to create the wiki. I’m saying, let the technical writer use a wiki as his or her documentation base. Make sure all project members are familiar with the wiki’s location and procedures for editing it. Then encourage the project team to comment, review, add, edit, and otherwise adjust the documentation through the life of the project. The writer can shape, stylize, make consistent, and organize the content to make it usable. Most likely the writer will write 75% of the content anyway, but it will be more informed and accurate.

(Thanks for the comments, Clyde.)

Madcap Flare Adobe Robohelp

This entry was posted in general, wikis on by .

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, DITA, and more. If you're trying to keep up to date about the field of technical communication, subscribe to my blog. Email

22 thoughts on “Using Wikis as Project Documentation Tools

  1. Pingback: just write click

  2. Pingback: CLUB MOSS - FRENCH

  3. Ross Mayfield

    Hi Tom —

    Great to hear you are using Socialtext for one of our better use cases. I’m sure your account manager can add more, but wanted to offer one public suggestion.

    Wikis traditionally and purposefully emphasize content over form. Doing so lets collaborators focus on the content that matters. Then you can format for presentation.

    I like the analogy of having people agree on business matters and then get lawyers involved.

    There are lots of tools that excel at presentation of content. But that leads to Powerpoint thinking and form over substance. Don’t let your team let these habits get in the way.

    Let us know how we can help further,

    Ross

    Reply
  4. Clyde Parson

    Tom,

    I was researching this myself the other day and came across the following that might interest you:

    There is an International Symposium on Wikis that has had at least two conferences. Their 2005 conference included a workshop on Wiki-based Software Documentation that may have resulted in some good information if you could locate someone who attended.

    I also found the following sites:

    Knowledge Management Wiki – not really a “how to” type of documentation but interesting anyway

    Fit Documentation – fairly sparse and lacking in navigation

    EvoCell Documentation – the content leaves something to be desired but I suppose that’s not the point for this discussion

    JSP Documenation

    Knoppix Documentation

    TinyMCE Documentation

    Reply
  5. Tom

    Ross,

    Thanks for the comment on my post. I love it when other companies are so aware of what is being said about their products. I was experimenting a bit with Socialtext and I like it a lot. I will have to read up on the documentation more. Thanks again for offering your help and expertise.

    Reply
  6. Isaac Garcia

    You should take a look at Central Desktop if you are looking for a Wiki-based Project Management Tool.

    Wiki’s can be too free-form and free-loving for a corporation to run an effective project from. Often times, the lack of structure is what breaks the system.

    http://www.centraldesktop.com

    (yes, I work for Central Desktop)

    Reply
  7. chris

    Hey Tom –

    You can generate documentation using a combination of custom columns, xml querying and the new XML Office formats. In our wiki, we’ve added two columns to a client wiki; (1) add to manual, (2) section of manual. The former is just a checkbox which you’ll use later in your query and the latter is list of sections which will appear in the document.

    From a high level, you’ll
    1. Query SharePoint using the webservice (http://site/_vti_bin/spsearch.asmx; there is a great tool from wsssearch.com here: http://wsssearch.com/querywebservice.html) making sure to add in the check for your custom column
    2. Format the returned xml in some form of fashion I like using xslt)
    3. Through code (Generation of Word 2007 Docs – http://msdn.microsoft.com/msdnmag/issues/06/11/BasicInstincts/default.aspx) build your document. The sections (determined ahead of time) and subsections (title of the wiki article) can be added to your Table of Contents, add in a nice template and presto – professional looking documentation from your wiki.

    Good luck.

    chris

    Reply
  8. Tom

    Isaac,

    Thanks for the product recommendation. It looks like a great wiki. Kind of costly, but probably well worth it.

    I think I will be limited to SharePoint 2007 because it’s the platform currently being implemented at my work.

    By the way, just curious, but how do you get to be so well-aware of the blogosophere? I think it’s awesome. Do you set up alert feeds based on keyword searches on google and technorati?

    Reply
  9. Tom

    Chris,

    Dude, that is exactly the kind of thing I am looking for. Thank you so much for responding to my post. I will be looking more carefully into this during the week and will probably follow up with some questions.

    Tom

    Reply
  10. Isaac Garcia

    Tom – as far as my/our web awareness its just rss feeds on certain keyword searches using Google, Google Blog Search, Technorati and Google Alerts. (we use a combination of RSS feeds as well as their various email alerts)

    The nice thing is that they are all free. Then, its just a matter of managing the RSS feeds – which is easy – we use Central Desktop to share these RSS Feeds for competitive awareness, research and to stay on top of “Central Desktop” and all relative keywords in the blogosphere.

    This allows our entire company to stay apprised of our markets and conversations about our products, services and our industry.

    The really nice thing is that this data goes beyond the Blog World now and spans most of ‘mainstream media.’

    Reply
  11. Pingback: Lars Trieloff's Weblog

  12. Pingback: Wiki research for an article about tech pubs and wikis « just write click

  13. Ross Nelson

    Hi tom,
    similar to using a wiki for project documentation, im currently trying to drum up the concept of using Wiki’s for Enterprise Architectures in IT. Basically when u start to explore them, Enterprise Architectures are a set of mulitple semi-structured facts all linked together, just like…. erm… Wikis. With EA by Wiki you wind up with pages about each application, installation, communication link, infrastructure element and standard within an organisation, all easily searchable and accessible and not stuck in some propellor heads brain or only known to the guy who quit last Tuesday.

    Ive started developing a prototype which can be access from my new blog on the subject at http://eabywiki.blogspot.com/ but it is still early days, and im using a free public online wiki for the demo. The lack of structure can be overcome with easily available good templates (the SP2007 Wiki doesnt really have this but its good in other areas) and a little bit of editorial oversight.

    Cheers

    Ross Nelson

    Reply
  14. Pingback: The Content Wrangler

  15. Pingback: Wikis in school projects? : Easy Idiot - get better knowledge

  16. Jason Shao

    Curious as to how people have worked out on this front. I love using wikis for docs, since they greatly lower the barrier to entry (and, erm, we need that to be looooow to make sure there *are* docs) though I struggle with how to fit versioning that into the SDLC along with our other artifacts – which makes me really like the idea of Maven sites, since the (java-centric) way we release programs would fit well.

    What does everyone think? How do you tie wiki docs with projects if they’re not versioned together.

    Reply
  17. Pingback: The Content Wrangler » Blog Archive » Using Wikis as Project Documentation Tools

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>