Raymond Chen, of Microsoft fame, has a great blog post entitled “If there’s a problem with a wiki, then you can fix it; that’s why it’s a wiki.” One paragraph stood out to me:
“In other words, if you see something wrong, fix it yourself. Don’t just stand around saying somebody should do something. Be someone. Because on a wiki, there is no default value for somebody.”
We’ve been using Atlassian’s Confluence as a wiki at work for ages, and love it[0]. They have a starter program where most of their software is $10 for 10 users. If your team is small and you’re not already using a wiki this is a great way to go. For $30 you get Confluence, JIRA (their issue tracker), and Team Calendars, and you can have them host it so it takes almost zero staff time to set up. How wrong could you go? If you’re a non-profit or open source project they’ll even give you a free license.
A couple of thoughts if you’re thinking about a wiki:
- The “just freaking fix it and move on” mentality is not a universal trait, especially in enterprises. Emphasizing that the documentation belongs to the organization and not an individual helps sometimes. So does gently encouraging people to fix things themselves.
- If you’re migrating documentation into a wiki make sure you delete all copies of the old source. It’s one of my fundamental tenets of sysadminnery that there should never be a non-authoritative copy of data or documentation sitting around. Leave a non-authoritative copy of a procedure sitting out there and you will discover, a year from now, that someone has followed it and all of its out-of-date ways. Grrr. Not that I’m bitter.
- Suppress the sysadmin need to be a complete permission freak. It feels wrong at first but a wiki’s content is meant to be chmod 770. Seriously. Wikis have history & revert functions if someone does something bad, but I have yet to see a case where permissions in a wiki did anything but hinder productivity & foster elitism. If someone wants to edit the docs you should let them. Hell, if someone wants to read your docs you should let them. They might learn something.
- Create a sandbox page, or if you’re using Confluence enable personal spaces so people can check out features in a safe environment.
- Wikis are great for meeting agendas. Not only can people add things to the agenda but you can add notes to the wiki while the meeting is going on. How cool is that?
—————-
[0] Well, I love it. There probably are people who don’t. They’re wrong.
I’ve seen how wiki’s in a Development environment change the accountability and discipline of the entire department. For my IT Toolbox, I use MS OneNote in a very similar way to cross reference issues, procedures, break/fix items, and as-built configurations. I dump everything in there, out of obligation to the organization. Its made me a better Administator.
And as for the permssions thing. Yep, wide open is best. What most don’t realize is the biggest threat to an organization is not a changed wiki page, but no documentation at all.
We also use Confluence and originally used it for all our documentation. However, for our code projects we eventually moved to using markdown files within the project Github repo. We found it difficult for developers to remember to keep the docs up to date when they were separated from the code. Confluence can also be quite heavy and slow.
This makes sense having the docs located right next to the code and although we have our infrastructure built using Puppet which has its own Github repo, we still use Confluence for the docs. This is because it goes further than simply being attached to the Puppet manifests – there are checklists, vendor details, diagrams and such. If we could, I’d move everything to Github but right now it still makes sense to use a wiki.