- Similar posts for 'python':
- Young Coders: Why twelve and up?
- Looking back and looking forward: 2014
- Katie learns Angular.js
- Teaching Python in your PJ's
- Why not self-publish?
- Similar posts for 'rant':
- Your wiki is a dump
- 5/18/15 - Announcing: PyCruise 2016!
- 2/17/15 - Young Coders: Why twelve and up?
- 12/31/14 - Looking back and looking forward: 2014
- 12/18/14 - Katie's Year of Audio Books
- 11/18/14 - Katie learns Angular.js
- 11/17/14 - Teaching Python in your PJ's
- 11/10/14 - Why not self-publish?
- 8/22/14 - My return to Pokemon
- 8/18/14 - What is a tech reader?
- 7/14/14 - Flask + git: Easiest workshop ever
Your wiki is a dump
11 December 2013
I freaking hate wikis.
Note that I’m not talking about things like Wikipedia or Bulbapedia (my two favorite wikis). Those are maintained by fanatics and are generally up to date. As long as you’re not on a controversial article, you’re probably safe to show it to someone to prove that they’re wrong about something.
But wikis need fanatics. They need people that will get het up over proper format for an article, or point out where you need a citation. They need people who are passionate about a certain topic who will haunt their pages and immediately check any change.
You know where we have wikis without fanatics? Our workplaces.
These commons are tragic
I’ve yet to hear of a tech company that operates without some sort of wiki. Maybe they’ve called it something fancier, like an enterprise dynamic document management system, but it’s still a wiki. Everyone can run around editing stuff. It doesn’t matter if you wanted to call it something more business-like. At the end of the day, you have yourself a wiki.
But corporate wikis are like the company fridge. Eventually, they get nasty. You get to the point where you know when someone opened the fridge, because you can smell it down the hall. There are terse emails and passive-aggressive notes, but none of that cleans the fridge. Why?
Because it is everyone’s responsibility, and therefore no one’s responsibility.
And that’s one of the features of wikis that drive me insane. Everyone can edit and maintain pages, so therefore, no one does. The health of the wiki is rent asunder because everyone assumes someone else will take care of the accumulating garbage.
What does a healthy wiki look like?
There are those that insist that wikis will always be a dump, as if this were a feature of wikis themselves. That’s not true. Wikis with fanatics tend to be fairly healthy. They’re more like a fridge with a few suspicious delivery boxes than a full-on disaster area.
So, what are the features of a healthy wiki?
- Search isn’t broken. I should be able to find what I’m searching for with relative ease. I should be able to do this using just a few search terms, and not by breaking out advanced search. Advanced search is a sign things are going wrong.
- The contents are accurate. I shouldn’t have to email someone to find out if a page I found is still accurate. No, a warning that the page is deprecated is not helpful.
- The contents are relevant. Every page should be immediately relevant to at least one user of the company. And not in a ‘gosh, remember when we had that crazy dev set-up’ kind of way. That person should need the information on that page to do their job today.
So how do we get into this mess where our wikis are completely useless? Well, we have some bad habits.
You don’t need to keep everything forever.
You really, really don’t. I swear. No one will care, two years from now, how we had search set up on those test environments that we ended up taking down and never using again.
I know that one of the features of wikis is keeping tons of information in one place, but you know what another feature of wikis is? Page history. If someone really needs to know about that (and you’re following better practices), they can find it.
No one makes sure that what’s there is actually accurate.
I’ve run into this so many times. I find the instructions on how to do something on the wiki. I try them out. They don’t work. I have never had instructions on a corporate wiki work the first time. I usually have to grab someone to figure out what in our crazy set-up is breaking. That’s when I find out that the instructions would never have worked. They either skipped steps, made assumptions, or were completely out of date.
Why was it out of date? Who knows! People either had their own instructions for setting up this feature, had gotten used to the missing steps, or had figured out how to do their job without it. No one passing by ever fixed the instructions, probably because we were so relieved just to have the feature working finally.
You put everything in the wiki. EVERYTHING.
Nothing drives me more mad than looking for the documentation on how Widget X works, only to find nothing but meeting notes about Widget X. Maybe, if I’m lucky, I find the actual documentation about Widget X on the third page of results.
There are so many things that do not belong on the wiki. They clutter search results. They make sections difficult to navigate. They give you more crap to maintain. Your wiki is a dump because you treat it like one!
You let too many people into the wiki.
Many companies have only one wiki. So useful! Everyone can search everyone else’s stuff and find answers across divisions! Oh, and we only have to buy one copy / keep one installation updated.
But this leads to organizational issues. One group may use the wiki as a dumping ground for meeting notes. Another may use it to document how their system works. Yet another might use it to discuss what they might want to include in their architecture. And then there’s that one group that puts cookie recipies up.
Also, the more people you have, the more diffuse the blame. If there are five wiki users (and no fanatics), there’s not that much blame to go around. Everyone has to pitch in. If there’s a hundred? No one is at fault because everyone is microscopically at fault!
You only have one wiki
People. You’ll buy everyone at your company MacBook Pros and Cinema Display monitors, and you won’t stand up one more wiki? Really?
There are free ones and they can be run off a thumb drive. I’m sure you can find the money and hardware somewhere.
So what are the good habits of wiki maintenance? Sure, it would be nice to get some fanatics in here to take care of this for us, but let’s be real. It’s a corporate wiki. We’re going to care more about who’s turn it is to bring in donuts, and what they’re stocking in the soda machine.
Break off into groups
The most effective wiki set-up I ever was immersed in was one where we broke off into groups. Design had their group. The Python people had theirs. Java had their own as well.
We could all check out each others wikis, but for the most part, we worked in our own. This kept the numbers down on each wiki. I believe each one had fewer than a dozen people who were active participants. The one I worked on daily had five people. This meant that there was tons of blame to go around if things went wrong, so we tended to hold our edits to a higher standard.
Decide what goes into the wiki
Maybe a group really does need to keep track of meeting notes forever. That’s fine! That’s a use case for that group, and they can feel free to put those notes in their wiki. Maybe they even have a wiki just for meeting notes.
My group tended to want things such as install instructions and notes on our architecture. We had notes about dealing with production issues, and important contact information. We kept our discussions to our mailing list, our meeting notes on a shared drive, and used our wiki as a snapshot of how stuff works today.
The front page is important
On most wikis, the front page is the most neglected page. Before my old group buckled down, we had:
- Projects that had been canned over a year ago
- Emails for people that had left two years ago
- Mailing lists that had been moved to another service, with a different subscribe email address
- Phone numbers to phones that had been given to other people, sometimes on different contracts.
- For some reason, a previous version of the page, saved beneath the current version of the page, like a dying man clinging to a raft.
My first act in the great razing was to remove all of that and post something more sensible. We had links to important pages within the wiki, but very little information on the page itself that would change. Why would we post that in multiple places and invite entropy in?
Decide on a structure
Structure is highly important. New pages should be made with caution, because every page you create makes the wiki slightly harder to maintain.
If it’s a technical wiki (and not a CYA wiki, which is what I call meeting note wikis), you probably want to have one page for getting your development environment up and running. That page should forever be the go-to for figuring out how to get everything working on your local. Another page might be dedicated to troubleshooting search (note, not SOLR. Search. You may change what you use for search one day).
Basically, the idea is to have every page be the one place to update information about a certain topic. I should be able to bookmark that page and go back to it, and get the most recent information about that topic. That’s how wikis work. How would you feel if you bookmarked the page on, say, Voyager, only to discover that someone had made a page called ‘Voyager - New page’ and started putting updates only on that. There would be a Wikipedia revolt.
History is your friend
You know how we’re just updating that one page with relevant information? That means we have to remove the information that’s no longer relevant. But fear not, wiki citizen. That information is not gone. It’s merely resting in the page history.
Should anyone care how we were doing things a year ago, they can look it up. If they want to see who decided to move remote the database setup from the install instructions, you can check that out. It’s like having the world’s most boring time machine.
No one is fixing that page when they have a deadline
Remember that no one is ever going to stop in the middle of a crisis and start fixing the install instructions. There are fires to be put out, deadlines to meet, and metrics to massage.
So, accept that this is a part of human nature and find a way to work around it. One way you might do this is dedicate time to cleaning out the wiki. Just like you probably ended up assigning someone to clean out the fridge, you’ll probably need someone to run through the wiki to make sure it’s up to snuff. They should verify:
- Any instructions work
- Groups and SME lists don’t reference people who have left
- Phone numbers and emails are accurate
- Working groups are accurate
- The architecture actually reflects what you’re using
You probably want to have this duty rolled around various groups. I strongly recommend a bounty so that it doesn’t get a vague nod before it’s passed on. My office has the ability to pipe in sound. I may ask that our bounty be the ability to pipe in one song of our choice at lunch time.
Note that I’m a remote employee. This makes the option that much more fun, though.