Wikis for technical documentation – Cliff’s Notes

If there ever could be a Cliff’s Notes for the wiki chapter of my book, I think I’m writing it now. I’ve been working on a great project with MindTouch. I visited them for a focus group with other technical communicators and technical support pros back in February in San Diego. We had open source community documentation represented, we had the health information industry represented, cloud computing, and high tech software writers, Agile writers, and document collaborators. It was a great time, discussing tips, tricks, and the trials of managing lots of content with specific purposes in mind such as learning, education, customer support, technical support, and internal collaboration. The write-up for how to run a focus group of this type is quite good – see Seek Omega: How to hold a Professional Focus Group that Produces Quantifiable Results.

After such a great session, we all continue to talk online thanks to one of the members setting up a LinkedIn Group, and MindTouch also invited us to work on a project to write up specifications for using wikis for technical documentation. We’re basically creating best practices using wikis for documentation, such as:

  • templates, such as DITA’s concept/task/reference as well as FAQ and solution guidance through multiple tasks
  • tags for workflow, assigning tasks, editing, and categorizing pages
  • content collection and curation
  • reports that assist with content curation and community documentation

I’ve been circling back with the members of the focus group while I write these specs, and working with Steve Bjorg, the CTO for MindTouch. His attitude towards development is,  create something with a sense of openess and collaborate with users as early as you can. It’s a refreshing way to make software. He describes these first go-rounds as the “Cliff’s Notes” for creating technical documentation with wikis. It’s not as robust as other solutions yet, but it sure does have features that are exciting glimpses at the future of documentation. I’ll post more in the coming weeks and months as we round out the features.

13 Comments

  • April 26, 2010 - 3:35 am | Permalink

    Anne
    What are Cliff’s Notes?

  • Kandis
    April 26, 2010 - 7:16 am | Permalink

    Hi Anne,

    Very interested to read those best practices. When will you be publishing them? Will they be publicly available?

    Thanks,
    Kandis

  • April 26, 2010 - 8:37 am | Permalink

    Hi Kandis – Yes, we plan to make them available, hopefully as part of the installation. I will post a few more blog entries as well because I welcome feedback on the templates and collections and user experience. I should be done with the first phase in the next two months, so stay tuned.

  • April 26, 2010 - 8:39 am | Permalink

    Hi Ellis – Cliff’s Notes are bright yellow and black summary and study guides found in the US and Canada for literature. Originally they were written as short guides to Shakespeare – there’s an interesting history written on the Cliff’s Notes site.

    Apologies for the US-centric reference – I meant to link to that history page from the blog entry and will correct that now.

  • Gina Fevrier
    April 27, 2010 - 10:30 am | Permalink

    I trialed Mindtouch and liked it. Importing Word docs from Robohelp and Flare was problematic because the pages couldn’t be reordered. Has that been resolved?

  • April 27, 2010 - 3:52 pm | Permalink

    What a great idea, to form a focus group around wikis for technical documentation, and even greater to base the specs for tool development on the findings of the group. It’s exciting that Mindtouch is recognising us technical writers as a target market in such an active and collaborative way. Go Mindtouch! I’ll be very interested in seeing the best practices too, when you’re ready to publish them. Good on ya, for planning to publish them to the world.
    Cheers, Sarah

  • April 27, 2010 - 10:59 pm | Permalink

    Hi Gina – The tech comm pros who are already using MindTouch have had to number their titles in order to get the results they wanted, so that hasn’t been changed yet that I know of. I do know of a large-scale import to MindTouch from XML, and I hope to blog about that soon (going through the right channels). :)

  • April 27, 2010 - 11:02 pm | Permalink

    Hi Sarah – So glad you like the focus group idea! The people I’ve been talking to at MindTouch really want to create in the open, it just instinctive to them. Thanks for commenting and I’m sure the best practices come from Confluence examples for sure. :)

  • May 14, 2010 - 9:22 am | Permalink

    Anne,

    Thanks for sharing this! I can’t wait for an update. Confluence and MindTouch seem to be the top choices for using wikis to create user documentation. I volunteered to contribute content on that subject to the STC’s Body of Knowledge project (but haven’t started yet). I hope other STC members will also contribute best practices (as well as requirements).

    Gina

  • Amanda Cross
    May 14, 2010 - 11:34 am | Permalink

    Hi, everyone,
    We use MindTouch for our documentation and have had pretty good results. We have run into some technical problems, but we really put the software through its paces and most people probably would not run into those issues.

    I’m not very happy with their business model, though. The per-user licensing for the Standard edition just doesn’t work for a company growing as quickly as ours is, and being stingy with users means we can’t be as inclusive about who can contribute.

    I would use the Core edition instead if they would offer support on it. Some days I consider switching to the Core edition anyway, just to avoid the user-license headaches.

  • May 15, 2010 - 9:11 am | Permalink

    Hi Gina – Great that you’re going to contribute to the BOK! I just started on the DITA page and it’s tough to distill to 5 -7 references and introduce the topic. Oh, what teachers of technical writing must go through. :)

    Hi Amanda – Thanks for commenting! I think their business model is interesting in that as a vendor, they are motivated to help you grow your contributor base. Some community building sites are charging by page view – which in the “attention economy” means the vendor has an incentive to help you improve web analytics, but hopefully they are also helping you grow your revenue as well. It’s an interesting time for collaboration and community vendors.

  • Pingback: Is Your Technical Communication Career a Dead End? | CloudAve

  • Pingback: Is Your Technical Communication Career a Dead End? | Seek Omega

  • Leave a Reply