Tom Hollander's blog

patterns, practices and pontification

GAT documentation in a wiki

GAT documentation in a wiki

  • Comments 2

Here in the patterns & practices team, people are inclined to go wiki-mad from time to time. We use them extensively internally for brainstorming and quick content creation, plus we have a bunch hosted on Channel 9 and elsewhere. A lot of this is due to the presence of wiki pioneer Ward Cunningham on our team - although it's important to point out that Ward doesn't pressure anyone to use wikis - he just gives this aura that seems to make this happen.

Content management and collaboration are topics that have fascinated me for a long time (in a previous life I designed much of the content management system that still runs the Australian Taxation Office's website). Wikis are particularly interesting as they provide a mechanism for anybody to enhance and evolve content without needing complex tools or processes. This has made us wonder whether wikis could be an effective mechanism for allowing the community to enhance and evolve certain types of patterns & practices guidance and documentation.

While I think this is a really interesting idea, I'm still not sure whether updating documentation is an activity that the community really wants to (or is in a position to) participate in. While some wiki sites are extremely successful (Wikipedia is the poster-child, of course), many others do not seem to have caught on, even some with some great ideas behind them (such as pinvoke.net). So what's the recipe for a successful wiki? While I have some theories, I really don't know - so we've decided that the best way of finding out is to do some experimentation.

Together with our good friends at ClariuS consulting who manage the GuidanceAutomation.net community site, we have published the complete documentation that comes with the Guidance Automation Toolkit (GAT) into a wiki. We're using this to test the waters as to how effective wikis can be to improve the quality of our documentation. Here's what we'd like to see happen:

  • If you are using GAT, and you'd like to share some of your experiences that will make life easier for other users of GAT, please update the docs in the wiki. This can include:
    • Clarifying or correcting text in existing topics
    • Adding brand new topics that you feel would be valuable
    • Restructuring existing content into a more intuitive structure
    • Adding code samples
  • If you are using GAT and need assistance, check by the wiki every now and then, in addition to the help that gets installed with GAT. Who knows, maybe you'll find some nuggets of advice from somebody else in the community.

We know that having the documentation fragmented into a static, offlline version, and the online wiki is less than ideal. We've discussed some ideas on how we could possibly integrate wiki content into the installed help to provide a more seamless experience. But this is just an experiment, and we'd like to get a feeling of how valid the wiki documentation idea is before we invest too much in the fancy stuff. If you have any ideas on what we could do to make this concept work well, please let me know by responding to this blog.

Finally, if you've used wikis before, you will notice that the GAT wiki doesn't require (or even allow) you to edit content in the traditional wiki markup language. Instead we built a simple "Wysiwiki" that lets you focus on the content rather than try to remember what markup tricks you need to get the content the way you like. While I'm sure some people will think this is sacrilegious, we felt it was important to lower the entry barrier to encourage more people to participate. And, for the record, Ward agrees :-)

  • I think you're on a good way with your Wiki documentation. Thanks for that, but please check the spelling of the subtitle on www.guidanceautomation.net:
    I guess you wanted to speak about software - not sotware... ;-))
  • I just worked my way through the GAT Hands On Lab from Teched 2005. Congratulations. These bits will be used! See my Blog for details...
Page 1 of 1 (2 items)