Using a wiki to manage your team project

03 Jan 2019 in

However simple it may seem to achieve, many development teams or projects don't maintain a central place to store their information. Sometimes, driven by a project task, someone may quickly set up a team page on whatever system their company provides, change the status of their task to 'done' and leave it at that. It is soon abandoned, lonely and unloved.

Without a dedicated area, team information moves arthritically around via email, or word of mouth - and that behaviour encourages gatekeeping. Using a wiki, all team members can have access to publish, read and update information about their project, and it soon becomes a valuable repository of the teams acquired knowledge. A team run wiki underlines the agile principles of self organisation and responsibility for reporting. It can also start to form or contribute to a 'Community of Practice' around the purpose of the project.

Atlassian's Confluence is the best enterprise wiki I have seen but if you don't have access to that, use something with the equivalent capabilities. Remember that a wiki allows team collaboration, allowing any team member to create pages and comment. If the only tool you have makes it hard to achieve these things, you're probably not using a wiki.

A team wiki primarily exists to answer the question where do I go to find out information about the project? Here are some example questions that a good team wiki can answer with a single URL:

  • Where is the project's Jenkins? The team's Jira? The code repository?
  • I'm a new team member. How do I start? Where and when is the team standup held?
  • I want to use something the team makes. Where do I go?
  • When is the next release?
  • What is the project's roadmap?
  • Where is the team physically based?

These type of questions will be germane to a project team and stakeholders throughout the project's lifetime.

Setting up, starting and maintaining your team wiki

So you have taken the job of administrating your team's wiki. There are three phases to go through when planning: preparing access, creating the pages with initial organisation, and day to day managing. While everyone should be contributing, a few dedicated guardians are needed to keep the wiki going when the project gets busy.

If your company or organisation doesn't have an internal collaboration solution such as Confluence, then if policy allows, use a public cloud solution. Before you establish your team's wiki (or 'space' in Confluence terms), make sure you understand the position of your team and project within an organisation. Is your project part of an ongoing transformation or initiative? A 'Line of Business' service? Does your project define the team members? Or is the team pre-existing? All these will help decide where and how to create your pages. Naturally, the answer to these questions may be complex or political but in my experience it is very common for a wiki to start life in the 'wrong' place.

You will need to assess who the current team members are and along with their identities on Lightweight Directory Access Protocol (LDAP).  You need to separate the 'pigs' from the 'chickens' - anyone can read or comment but content creation should probably be reserved to those with their skins in the game. Through the lifecycle of your project, team members will be added and removed (even possibly you), so administration rules need to be established; don't make yourself the sole 'wiki person'.

The first pages, which establish the forward direction, should clearly display the team and/or project name, have a table of important information and a team member listing. If you are using Confluence, make use of page layout sections and add a mission statement near the top of the page, which can aid recognition of the wiki. A section for people who are new to the project is usually appreciated as well.

The day-to-day tasks are vital to keep the site relevant and fresh. Big changes to staff or primary project URLs are relatively uncommon, but spreading information about a recent release issue or the highlighting the latest team ideas on automation become regular tasks.  Maintenance, including the removal of old or redundant pages, is also vital, as team members forget to 'prune' their own pages and in most cases won't have permission to delete content anyway. When trying to identify pages to remove, look out for ones with no incoming links, lack of recent activity and out-of-date information. However, if necessary, an 'out-of-date' page can be made to allow any user to move their old pages for later deletion. 


There are several collaboration techniques with a Confluence wiki, so make sure you and your team understand them. 

  • Editing the page directly. If a team member wants to enhance an existing document or piece of information, they just do it. If you write as the same time as someone else, Confluence will try to merge the changes, or at the very least show you where the differences are. Pages have their own history, allowing you to revert to older versions if you make a mess.
  • Inline comments (select a piece of text and hover over). This preserves the original text but informs the author there is an issue with a selected passage. The author can then resolve the issue if required, avoiding merge issues.
  • Comments at the end of a page. These are best used when you want to start a conversation about the contents of the page as a whole.

General tips and macros

  • Don't use security as a reason not to publish important team information - use a restricted page. For example, put all current project related credentials on a restricted page.
  • Use the simple status macro to indicate whether a document is still in progress, or ready for review.
  • Use the User profile macro to create a team list. When mentioning users, use their '@' names.  
  • Always use page layout to split the page into sections - never force people to read one column that is the width of their screen. 
  • Use the excerpt macro to highlight the first paragraph of a page in a contents list.
  • Depending on your laptop and Confluence version, you can generally just paste an image directly onto a page - Confluence will attach the image to the page for you.

So forget about emails, avoid shared Word docs and ignore word of mouth, having a centralised area to share information can boost your team's productivity and collaboration. By utilising a wiki page, all team members have up-to-date project details, which removes the reliance of gathering second hand information, which can delay projects being successfully completed.