TL;DR Wikis are awesome tools. When used poorly, they’re like black holes; documents disappear into the ether. When used intelligently, they can be powerful, self-organizing knowledge centers for your team.
On most large software projects, organization is key. Developers aren’t always the most organized people in the world (I’m no exception) and project managers tend to focus on the project schedule. This can leave something to be desired or tracking the team’s progress and keeping everyone on the same page in terms of technical decisions and understanding of the larger system architecture as the project progresses.
Most projects hit a speed bump or two along the way, and it isn’t uncommon to have people scrambling trying to remember what was agreed to and when or struggle to remember why or how a certain decision was made.
Technical Meeting Notes
How many times have you walked out of a meeting scratching your head thinking things like “what was the point of that meeting?”, “what did we decide here?”. And of course one week later, you wouldn’t have a prayer of remembering what you did at all last week!
On large projects, I’m a fan of regular (usually weekly) team meetings to discuss issues and progress. They help keep the team on track and unlike daily standing meetings, focus on the bigger picture. In my experience, they tend to capture and more meaningfully address project obstacles, free from the constraints of short time-boxes. They can also be a great counter-balance if you’re team is struggling with zombie scrum. For these meetings, I like to keep structured meeting notes. These kinds of meetings are infrequent enough to be practical to do this, but also long enough for it to be important.
It takes some discipline to keep it up, but it’s well worth it. Make sure there is a designated wiki meeting notetaker. It can just be scratch, with possibly a bit of elaboration done after the meeting. This is a format I like to use that’s simple:
1. Put a date on it, in the title. Captures chronology. This is really important.
2. Attendees – make sure you know who was there.
3. Goals – have clear goals for your meeting or don’t bother; it will just be a waste of time.
4. High-level discussion items including who raised them and relevant but concise notes.
5. Action items with assignees – these are generally the key take-aways from the meeting.
This is all common sense stuff, but having a set template is a great help in staying consistent (see the tools section below). Aside from capturing important discussions, meeting notes help create good visibility to a team’s progress, so everyone is on the same page about where things are at, or to catch up if they missed it.
While you might touch on these in the technical meeting notes, its an excellent idea to document the decisions themselves in their own right. Many complex architectures can be boiled down to just a handful of key decisions. It can help combat the problem of over-reliance on the original developers or architects. Another benefit is new team member ramp-up: reviewing important decisions can help provide critical context and rationale for a new developer before they start diving into the code.
I like to make this documentation include:
1. Background/context on what the decision relates to
2. Who was involved in the decision
3. Rationale behind the decision
4. Explicit discussion of the trade-offs, and recognition of limitations in each case. You can also use these as a checkpoint for sign-off from product owners, management, etc if necessary.
5. Decision status – is it decided yet? It’s OK for a decision to be a work in progress while the options and trade-offs are being identified and considered. Just document that a decision needs to be made and track its status. You can then flush out the considerations and trade-offs as you go. You may find that it really helps you enumerate what the trade-offs actually are, and can make you feel more confident with the decision that you do make.
Leverage the tools to keep things self-organizing
Even the best wiki tool in the world won’t keep itself organized without some effort or curation on the part of the team, and this is often where wikis fall apart and loose their utility.
Use tags & widgets to keep related content dynamic and self-organizing. Here’s some things I find work well:
- Tag, tag, tag. Is there any system that isn’t made better with tagging? Use tags on all the content you create. It’s the building block for so many useful organizing tools. Be adamant about people tagging the content they create. Even better, use templates that include auto-generated labels where possible. E.g. a meeting notes template which includes a `projectA-meeting-notes` tag
- Create top-level hierarchical organizations based on tags and use widgets to pin nodes in the hierarchy so that the documents remain grouped over time and as new content is added.
- Use search widgets that scope searches to relevant areas of the wiki to prevent poor search results
- Use templates. Make your own custom ones if need be. They help automate the tedious aspects of keeping a wiki organized and maintain consistency across content created.
At work, we use atlassian’s suite which includes Confluence for wikis. It already has a bunch of useful widgets and templates for all the things mentioned here, which is where I discovered just how powerful and useful they were.
Have a wiki space just for your team
Don’t create documents important to your team in a company or department wiki space. You’ll want to focus the content in your wiki to the right audience, and if you put it in a larger wiki it will make it difficult for someone to know whether a document matching their search criteria will actually be relevant to them (e.g. a product requirements doc on a feature vs a technical architecture one).