Awesome Conferences

Reorganizing a wiki or documentation system

Someone wrote to me recently asking for advice about how to re-organize his company's documentation stash. Basically they had a directory on a fileserver that had become a free-for-all, collect everything, "cosmic abyss" (his words). Tons of documents. No organizations. Most of it out-of-date or of unknown quality.

Did I have any advice that didn't involve complex document control philosophy and best practices?

Sure!

Here's a strategy I've used at 2 different organizations. It is very simple and low-overhead:

Find a way to mark all old docs as "old", then find a way to review docs and mark them as "reviewed". You might convince your team to do a day-long "review day" (or maybe "week") where other projects are put on hold and people try to do all the reviews. What doesn't get reviewed is just left somewhere that people can find.

We recently re-organized our wiki at Stackoverflow.com this way. We made 5 new subfolders: procedures, servicedocs, templates, styleguides, policies (plus a "trash" subfolder). We moved all legacy docs (the entire hierarchy) into a subfolder called "unreviewed".

To track the reviews, we listed all the unreviewed doc in a google spreadsheet. The spreadsheet had 3 columns: filename, volunteer, status.

We picked a day to do our "wiki fixit". People spent a day reviewing docs and had permission to put all non-emergency work on hold. They'd pick a doc to work on and write their name in column 2 of the spreadsheet to "own" it. They'd review the doc, moving it into the right folder (or "trash"). When done, they'd write the word "DONE" in the "status" column. In a day we got all the important docs reviewed and moved into one of the 5 new places. The remaining docs were mostly obsolete crap.

Weeks later we would still find an occasional doc that was still "unreviewed" but it was easy to move it to the right folder. Some day we'll be brave and remove the "trash" and "unreviewed" folders but its only disk space so that day may never come.

This was nice because it gave us a 'clean slate' feeling but converted the important docs.

If you haven't used a multi-user spreadsheet for something like that I highly recommend it. Everyone can see what everyone else is doing. You can reserve in advance docs you want to work on. It creates peer-pressure to get a lot done, since everyone can see who the laggards are. It also creates a record of who got how much done; which is useful if you want to gamify the process and give rewards for most documents processed, etc. A good way reward IMHO is to have the company take everyone out to dinner at the end. To go to the dinner you must have participated. The person that completed the most docs gets to pick the restaurant.

Posted by Tom Limoncelli

2 Comments

Out of interest which wiki platform do you use/recommend

I don't have a favorite. I tend to use the one buit into Github/Gitlab.

Credits