Team wiki tips and tricks?
March 21, 2014 11:41 AM Subscribe
We are a large team, familiar with wikis, feeling disillusioned because the wikis always end up being a giant mess. What conventions can we adopt to make our wikis better?
I work on a 100-ish person team inside a large corporation, developing software. For each project, we set up a wiki to store documentation, tutorials, and so on. Almost everyone on the team is technically adept enough to create or edit a wiki page, and a decent number of people are also willing to do so, so we definitely get content added to project wikis. Our corporation provides Confluence wikis to us, and there is a whole department that handles the backend, so we don't have to worry about that. Also our wiki has to be locked down so no-one outside the team can see it, so we need to stick with the corporate-hosted Confluence wiki.
However, people are gradually becoming disillusioned with wikis, and with the start of a new project, we are trying to do it better this time around. Issues we typically run into:
1. It becomes a hugely disorganized mess, making it hard to find anything. We typically set up a basic hierarchy at the start (department sections, each with child sections for tutorials, specs, etc), and people stick to that structure, but the number of child sections multiplies out of control and often things arguably belong to multiple categories or departments, so it gets confusing. I am considering suggesting a much flatter, broader structure, so there would be less hierarchy, which means less pages, but they are more link-heavy to scroll through and find the thing you want.
2. Stuff goes out of date and no-one notices. New people join the team, get pointed to the wiki for tutorials or specs, and then when they ask questions about the content we realize that the pages are horribly out of date and there's a huge scramble to quickly write new ones.
We do not have anyone with the role of wiki master, and this is not going to happen. I want to set the thing up with a plan in mind, communicate that plan to the team, and hope that it goes better than usual. No-one has time to really police it. What has worked for your team? How have you addressed issues of organization and keeping things up to date? What conventions have you come up with to make it work better?
I work on a 100-ish person team inside a large corporation, developing software. For each project, we set up a wiki to store documentation, tutorials, and so on. Almost everyone on the team is technically adept enough to create or edit a wiki page, and a decent number of people are also willing to do so, so we definitely get content added to project wikis. Our corporation provides Confluence wikis to us, and there is a whole department that handles the backend, so we don't have to worry about that. Also our wiki has to be locked down so no-one outside the team can see it, so we need to stick with the corporate-hosted Confluence wiki.
However, people are gradually becoming disillusioned with wikis, and with the start of a new project, we are trying to do it better this time around. Issues we typically run into:
1. It becomes a hugely disorganized mess, making it hard to find anything. We typically set up a basic hierarchy at the start (department sections, each with child sections for tutorials, specs, etc), and people stick to that structure, but the number of child sections multiplies out of control and often things arguably belong to multiple categories or departments, so it gets confusing. I am considering suggesting a much flatter, broader structure, so there would be less hierarchy, which means less pages, but they are more link-heavy to scroll through and find the thing you want.
2. Stuff goes out of date and no-one notices. New people join the team, get pointed to the wiki for tutorials or specs, and then when they ask questions about the content we realize that the pages are horribly out of date and there's a huge scramble to quickly write new ones.
We do not have anyone with the role of wiki master, and this is not going to happen. I want to set the thing up with a plan in mind, communicate that plan to the team, and hope that it goes better than usual. No-one has time to really police it. What has worked for your team? How have you addressed issues of organization and keeping things up to date? What conventions have you come up with to make it work better?
I had to set up one of these in my job for a similarly sized organization.
I'm not entirely clear whether the material you're putting on this wiki is internal or product documentation, but in any case the best way to get people to use it is to make it the easiest thing they can do.
It becomes a hugely disorganized mess, making it hard to find anything. We typically set up a basic hierarchy at the start...and people stick to that structure, but the number of child sections multiplies out of control
Don't treat the Confluence page structure as "the" hierarchy. It's just one way to get to the information you want. If people are sticking to the structure, the fact that this structure becomes unwieldy is an inherent property of the information, not really something you can fix. On the other hand, the useful thing about this structure is that people know and understand it. Bringing in a new structure would add a risk that more of your contributors will just give up.
often things arguably belong to multiple categories or departments, so it gets confusing.
Wikis rely on pervasive links. Links everywhere, not just the hierarchy. Increase the number of navigation possibilities by creating portal pages to group links to things which ended up separated; using labels; ensuring that search is good and useful.
This might show up some weaknesses in higher level information policy: in my company we didn't all use the same name for the same thing across departments anyway, which caused problems generally, not just for the wiki. Oh and central IT replaced the search confluence box with a "search confluence and sharepoint" box that delegated to sharepoint's comically bad search facility. *grar*
I would consider keeping the structure that just-about-sort-of works, but treat it as more of a filing system than a navigation system. Just one way to access the information, whose main (only?) benefit is that it's logical and everything is in it somewhere.
We do not have anyone with the role of wiki master, and this is not going to happen.
OK so this means you are wiki master. The buck has to stop somewhere. If you don't have time for this then you need to explicitly distribute all the responsibilities of wiki master, spreading them thinly enough that they don't piss anyone off. So everyone must take a (small) amount of time to police the wiki. This is not easy among 100 people. Is there a way you could split up the wiki into sections which can be overseen by smaller teams (say 5-10 people)? Give each team some scope for experiment with the structure and content of "their part" and allow teams to learn from each other.
Stuff goes out of date and no-one notices. New people join the team, get pointed to the wiki for tutorials or specs, and then when they ask questions about the content we realize that the pages are horribly out of date and there's a huge scramble to quickly write new ones.
To be honest, this might be the best way to go about it. You are updating pages at roughly the rate that they are viewed. It feels disorganized but it may be more efficient than maintaining a huge documentation set that nobody uses, particularly since it sounds like (as is the case in my organization) you're practically expecting people to do this maintenance work in their spare time.
I do have one concrete suggestion though: allow, and encourage, people to delete summarily any stuff they find that is out of date, even if they didn't write it, and without any expectation that they will replace it with a corrected version. If information is not there, the new guy will ask someone to fill them in. If it is incorrect, new guy will work off of incorrect assumptions and things will go badly. You may not find out about the misunderstanding until several months later. It feels bad summarily trashing somebody else's hard work, but everyone's work has a shelf life. and you can rescue it from page history anyway if there is a blunder. This might also help with the information bloat issue.
Good luck!
posted by doiheartwentyone at 3:06 AM on March 23, 2014
I'm not entirely clear whether the material you're putting on this wiki is internal or product documentation, but in any case the best way to get people to use it is to make it the easiest thing they can do.
It becomes a hugely disorganized mess, making it hard to find anything. We typically set up a basic hierarchy at the start...and people stick to that structure, but the number of child sections multiplies out of control
Don't treat the Confluence page structure as "the" hierarchy. It's just one way to get to the information you want. If people are sticking to the structure, the fact that this structure becomes unwieldy is an inherent property of the information, not really something you can fix. On the other hand, the useful thing about this structure is that people know and understand it. Bringing in a new structure would add a risk that more of your contributors will just give up.
often things arguably belong to multiple categories or departments, so it gets confusing.
Wikis rely on pervasive links. Links everywhere, not just the hierarchy. Increase the number of navigation possibilities by creating portal pages to group links to things which ended up separated; using labels; ensuring that search is good and useful.
This might show up some weaknesses in higher level information policy: in my company we didn't all use the same name for the same thing across departments anyway, which caused problems generally, not just for the wiki. Oh and central IT replaced the search confluence box with a "search confluence and sharepoint" box that delegated to sharepoint's comically bad search facility. *grar*
I would consider keeping the structure that just-about-sort-of works, but treat it as more of a filing system than a navigation system. Just one way to access the information, whose main (only?) benefit is that it's logical and everything is in it somewhere.
We do not have anyone with the role of wiki master, and this is not going to happen.
OK so this means you are wiki master. The buck has to stop somewhere. If you don't have time for this then you need to explicitly distribute all the responsibilities of wiki master, spreading them thinly enough that they don't piss anyone off. So everyone must take a (small) amount of time to police the wiki. This is not easy among 100 people. Is there a way you could split up the wiki into sections which can be overseen by smaller teams (say 5-10 people)? Give each team some scope for experiment with the structure and content of "their part" and allow teams to learn from each other.
Stuff goes out of date and no-one notices. New people join the team, get pointed to the wiki for tutorials or specs, and then when they ask questions about the content we realize that the pages are horribly out of date and there's a huge scramble to quickly write new ones.
To be honest, this might be the best way to go about it. You are updating pages at roughly the rate that they are viewed. It feels disorganized but it may be more efficient than maintaining a huge documentation set that nobody uses, particularly since it sounds like (as is the case in my organization) you're practically expecting people to do this maintenance work in their spare time.
I do have one concrete suggestion though: allow, and encourage, people to delete summarily any stuff they find that is out of date, even if they didn't write it, and without any expectation that they will replace it with a corrected version. If information is not there, the new guy will ask someone to fill them in. If it is incorrect, new guy will work off of incorrect assumptions and things will go badly. You may not find out about the misunderstanding until several months later. It feels bad summarily trashing somebody else's hard work, but everyone's work has a shelf life. and you can rescue it from page history anyway if there is a blunder. This might also help with the information bloat issue.
Good luck!
posted by doiheartwentyone at 3:06 AM on March 23, 2014
This thread is closed to new comments.
posted by Bentobox Humperdinck at 12:11 PM on March 21, 2014 [2 favorites]