Why Wiki?

In OpenStack-land, the wiki was chosen before I got here. It has a couple of flaws for my vision for open source documentation, which became more apparent when I recently outlined my reasoning for what content goes where. By walking through the “what goes where” talk about documentation and audience, I realized something about the system we have set up (and will tweak more) and it’s this: a wiki revisions a page at a time, but our doc system with comments revisions a site at a time, namely a release at a time. It’s an important distinction to make so that you decide what a web “page” contains. It’s important to be able to articulate your needs for a web page and how it’s updated so that you can tell authors how much information you need in a page.

A page at a time is really tough for ongoing maintenance, when you don’t choose correctly the amount of information in a page. There are also difficulties with the rather immature technology in many wikis. Wikis were designed for simple editing, fast publishing. What if you have a sweeping name change? Anyone doing tech comm in a wiki knows that’s a headache for many wiki systems. What about a final spell check? Page at a time. How about search and replace? Page at a time. And let’s not talk about the times when you have to add an entire column to a table in an ASCII-based wikitext way. Your wrists will revolt, I assure you.

But an interesting expectation for a wiki that wasn’t considered when choosing the wiki is the need for comments on each page. Right now the only web systems for OpenStack that enable comments on a page are the OpenStack blog and the docs site. The docs.openstack.org site is built with DocBook XML with Disqus comments embedded on each page. It’s not quite perfect, as we’re learning as we go that not everyone wants to moderate every comment from every book on the site, and we’re still learning how to turn off hundreds of comments at a time, but it’s a great solution to a specific need. Yes, even the comment system selection needs an information architect analysis before you begin, but that’s the topic of a future post.

Ironically, our wiki doesn’t have a way to comment. So we just use it for project documentation and any comments on a project design are actually done in person at a Design Summit, which is coming up next week. Even with the great opportunity for in-person interaction at the Summit, I get the feeling there are more people wanting to “talk back” and give feedback. And certainly people want to receive feedback, to a point where they specifically bring docs to me and request publishing through the docs.openstack.org system due to the commenting system.

So what this meandering post is coming around to stating is this: You don’t need a wiki to gather feedback on your docs. Find a way to embed comments on each page and a way for collaborators to edit and you’ve got two of the basic end-goals done.

Now, make sure the end goals are known in the first place. It’s possible you need a wiki because your information would be best written a page or an article at a time. This statement is obvious when looking through your hindsight lens but difficult to be disciplined enough to state in the first place. Answer the question “why” about five levels down and it’s likely you have a solution. It may or may not be a wiki, but it’s certain that if you’re producing web content, readers have certain expectations about the content when they come to it.


  • October 4, 2011 - 9:23 am | Permalink

    We use Twiki within the company I work for to make internally public to employees the procedures within the account and to spread tips and tricks about projects we currently develop. It turned out that usingt Twiki is very useful, people really contribute to spreading info, most of them coming with improvements, more useful informatiopn. As you state we use it as an OpenSource platform for useful info (for projects). The info editing is accessible to anyone within the company and people take it very seriously.

    Regarding Wiki for documentation delivered to our customers, not sure we could do that. Wiki works perfectly for open soruce projects..

  • OpenStack doc bug
    December 1, 2011 - 11:16 am | Permalink

    Couldn’t find another place to submit a documentation issue for openstack, so sorry, I’m dumping it here. The datasheet at http://openstack.org/downloads/openstack-compute-datasheet.pdf has a font that isn’t available for many people (EKCOMP+MyradPro-Cond), so all the text is unreadable. Any way someone could repost that document with a universally available font?

  • December 1, 2011 - 11:21 am | Permalink

    Hi, you can use the openstack-manuals project on Launchpad to log bugs against content on openstack.org. I’ve logged https://bugs.launchpad.net/openstack-manuals/+bug/898709 for you, thanks for reporting. it.

  • December 2, 2011 - 5:05 pm | Permalink

    Wanted to let you know we’ve fixed the PDF download for the OpenStack Compute Datasheet. Let us know through the bug at https://bugs.launchpad.net/openstack-manuals/+bug/898709 if it works for you.

  • Leave a Reply