Developers Need a Community of Practice — and Wikis Still Work
“Hi. I started yesterday. So… how do I get onto the corporate email server?“. The developer shifted in his chair, pushed his glasses up and stared blankly into his laptop. “Oh, I guess, er, try emailing the admin?”
Fortunately, the days of everything being done on email chains is slowly coming to a close, but scenes like the above still happen, because once you’ve exhausted the details in your HR starter pack, there are still a heap of questions with no immediate answers. The classic response is that a guy called “Rick” will guide you through, but, of course, Rick Isn’t Here Today.
The main way to avoid Rick dependency is the team wiki, which displays team information and keeps it fresh. On a larger scale, capturing enterprise expertise is the purpose of a Community of Practice (CoP):
“A Community of Practice is a group of individuals who share a common interest or profession and engage in ongoing communication, collaboration, and knowledge sharing to enhance their skills and knowledge in that domain.”
That’s a quote from ChatGPT; and who am I to doubt that source? Of course, these things don’t just appear on their own, you may have to take responsibility to create a CoP and maintain it. This post looks at doing these ‘softer’ aspects of software development — knowledge capture.
In some respects, the CoP exists as a counterpoint to the team wiki. Whereas a team (or project) wiki should answer questions like “where is the team repo?”, the CoP will have discussions on sharing Ansible playbooks and similar. Whereas a team is a ready-made community, so to speak, the CoP has to be forged — from both the willing and the less forthcoming. But they both need wikis to thrive.
Choose a Wiki, If You Can
In modern slimline companies, self-documentation may be built-in; but in less progressive organizations, any activity that doesn’t directly push product out of the door can be looked upon as excess. Even getting access to a wiki may not be simple.
There are a lot of wiki systems out there, especially if there is no intranet to get around — Atlassian’s Confluence is popular and good, Microsoft’s SharePoint is neither, but whichever gets accepted there are a few key attributes.
Secure pages (ones that can only be seen by team members) are a great solution to maintaining secrets and passwords.
Fine-grained user roles and permissions allow for an inner core of maintainers who can (for example) delete posts. Having only Full access or Read-only is a little too ham-fisted.
Wikis that use pure markdown will be more generally useful, but even developers like full WYSIWYG solutions. Maintaining columnated pages is vital for text organization. I have to admit, some of the smaller wiki projects tend not to include these quality-of-life additions that can encourage people to use the system more.
Dissecting the Team Wiki
Whether a team or a project page, one of the surprisingly useful things is just to describe what the project is for. After a few transitions, many teams no longer have a specific purpose, but they still have a timeline that can explain their skill set neatly. Projects can suffer like this too, but again just documenting their inception along with describing their current aims makes so many oddities clearer. If you find that this information is unavailable, that might be a red flag.
The front page of the wiki should show a list of the team members, the project description, and maybe the time or name of the next release. The most relevant and useful links will be for the build or continuous integration servers, the stories and tasks, the central repo, the issue logs, the release checklists, and the various specific problems that could block other team members.
As mentioned above, secure pages also should help team members find up-to-date passwords or configuration secrets. A separate page should be dedicated to serving new starters. Other pages can be used to list third-party and dependent relationships. Simple information like where the QA team are based can help you respect their timezone when communicating.
There will probably be other “information radiators” in a project, and a team wiki will probably refer to these. That doesn’t mean they should necessarily all be carefully integrated. Atlassian has done a lot of work to collect together strong tools like Confluence, Trello and Jira — and all these tools are now AI-powered — but don’t sacrifice better tooling elsewhere just for a single sign-on. If you can’t refer to your other tools through simple HTTP links, that is unhelpful.
The most important aspect of wiki maintenance is simply doing it regularly, much like gardening. Prune away old articles — or better still, archive them. Update the next release date, changes in team membership, calendar events, etc. Because the last activity date of any article is usually visible, people will steer away from any content that looks dead.
In summary, any information that you would have to ask a team member for, or gets stuck in email chains, or gets repeated multiple times — all of this should be on the wiki.
Thoughts on Community of Practice
This subject has flattened out a bit since the pandemic, after which fewer developers worked next to each other and keeping remote members connected is more the norm. A good Community of Practice should just look like a private Stack Overflow, with discussions on topics of concern to devs across the organization.
This applies to most organizations that have siloed teams. If you are part of a one-team company, then a CoP should not be something you need right now — just be ready to be proactive when you are part of a bigger setup.
The first seeds are usually sown when “best practice” is discussed, and managers realize that there is no point in having just one team getting things right. This is the time to establish a developer CoP, before something awkward gets imposed from above.
The topics are often the complications that an organization stubbornly brings to existing tech; like understanding arcane branching policies, or working with an old version of software because it is the only sanctioned version, etc. I remember that provisioning resources from a private cloud was a common grumble in one place I worked at. Sometimes policy discussions on the relevance of open source solutions. There are a variety of problems that can prove to be absolute blockers, that someone in another team may have solved. Along with that will come discussions on tabs vs spaces, and EMACS vs VIM; but a CoP is a social space, so this is to be expected.
Comparing team procedures can be invidious, but is a solid way to push best practice throughout an organization. Not only can innovations be picked up, but advanced warnings of problems can also be noted. Release procedure, because it gets the most attention when it fails, is a good example here.
A Community of Practice does need steering. You need to notice if any hot-button issues are drowning other areas, and you also need to keep the mood constructive. You may also need to persuade people to contribute — and this often means having to dig into how recognition and bonus schemes work. Very few developers care for this type of machination, and it probably does need a degree of managerial guile.
Maintaining a CoP is best done by a fairly senior dev, because there will inevitably be pushback. There is a degree to which a CoP works against corporate discipline. We all know that managers like silos despite what they say, because it appears to keep team members focused on local issues and offers a degree of security through compartmentalization. A CoP can help undo the intellectual damage done by silos, but this needs to be handled with a little discretion.
