Developers don’t like writing documentation, generally. — Knowledge sharing in tech teams seems to be a recurring problem. While it could solve a lot of problems (like allowing swift onboardings, unavailability of the colleagues or high turnover with knowledge loss) and many tools exist to make it easy, team members don’t always want to participate in the effort.
In this article, I’ll explain how knowledge sharing can benefit everyone, individually and at team level, how to foster a culture of sharing in a team, and quickly talk about some existing tools and good practices.
I’ll be talking about knowledge that is usually passed orally, explanations that go beyond the technical documentation and knowledge that is gathered by someone from working on a project/in a company, by experience.
Some ideas found in this article
- Being dispensable is a good thing!
- Sharing knowledge doesn’t make you disposable.
- Sharing knowledge allows to learn and make progress.
- Encouraging knowledge sharing is only possible in a healthy team.
What’s in it for me, as a software engineer
Before even talking about the benefits for the team (because I know they could raise a lot of Yes, but…), I’d like to show how sharing your knowledge with the team benefits you at individual level, either you’re a junior or a senior.
Become “dispensable”
I think the number one fear when sharing knowledge is that, once others know what you know, you’re not indispensable anymore. So I want to explain how it might not be true, but also why it’s a good thing.
At first, hiring and firing someone costs a lot to the employer. We’re all aware that hiring in IT is super difficult and that the competition between employers is huge. So if your company thinks of firing you, I guess they’re is a really bad position (like, going bankrupt or losing a big contract) and it’s a good thing to go elsewhere anyway…
Also, sharing your knowledge doesn’t mean anyone could do your job using your notes. When I was working as a freelancer (in another field), I once shared the precise plan of action I intended to put in place with a potential client, together with my offer, because I knew they had a hard time understanding the whole workflow. Two days later, they started searching for an unpaid trainee to make them do the task thanks to my note (without telling me and without my consent of course). Guess what, the implementation made by the trainee was a mess, nothing like what I intended to do. My notes were clear (with terms that you could easily find on the Internet if you didn’t understand them), but apparently only someone with my understanding of the problem and the processes could have done something with them. Little chances the client could find a spare freelancer for a lower price for the job. Knowledge sharing is not about making a digital clone of you that makes you disposable, it’s about sharing crucial information to allow the team to work efficiently and allowing everyone to grow.
Now, all the negative ideas aside, let’s see how being dispensable is a good thing: have you ever met that person, working on a shitty project, either with a really annoying client that drives them crazy, or on a super legacy project no one wants to touch. See, that person, there’s a really high chance they’re the only one who knows about that specific project, for some reason there was never any knowledge sharing, and now they’re literally stuck with it. I guess it’s nice if you want to spend years and years on the same work item and you’re ok with it… but I think most of us like to change projects from time to time (or often) and grow with the technologies.
Find the information later
I take a lot of notes when I get explanations from someone. Messy notes because one can’t write as fast as someone speaks. Then I spend time writing again my notes in a clearer way, completing them with my researches when I’m not totally confident about something. When it might be interesting for other team members, I don’t see a reason not to write this documentation on a shared space instead of keeping it for myself.
Also, I used to write them in a note book (yeah, papers, remember those?) until one day I needed an information that I received two weeks earlier but forgot my note book at home. As I hate asking the same question twice (especially when it’s a long explanation and everybody’s pretty busy) I started using our team wiki directly instead of using an individual paper notebook and eventually create the documentation.
Consolidate one’s knowledge
I started writing this blog because I realized how having to explain something allows you to notice things that aren’t clear for you, then focus on them in your learning journey. I think it’s exactly the same for team documentation: it allows you to check what you know, what more you could know, but also how much you have learnt (and that’s satisfying in a job where your ego can easily be hurt 😂).
To a certain extend, I see it as a must in order to evolve to a role with more responsibilities, to become the one who can mentor others or lead a dev team. Explaining and teaching is usually not a skill you’re born with, so this is a good exercise.
Identify complexity in processes and architecture
This is linked to previous point: if something is really really difficult to explain, even by those who know it the best, maybe it’s too difficult or complex and it could use some refactoring.
For the team
I think (well I hope…) those are pretty obvious so I won’t go into much details:
- Limit heavy refactorings and errors found during code review.
- Ensure the communal understanding of the business, team contract, tools, infrastructure…
- Allow people to do their work when the knowledge holders are busy (well in fact, avoid having knowledge holders…).
- Allow people with more seniority in the team to work with less interruptions.
How to foster a sharing culture
- Fostering a sharing culture means fostering team spirit. This is the biggest challenge to me, because it involves working with people, taking into account their experience, their personality, how they feel in the company and the team, how confident they feel with themselves… This is a bigger challenge with no easy solution, but I would just say to anyone managing people: make them happy, listen to them, respect them, otherwise there’s no reason for them to make your life easier.
- Encourage “collective intelligence” in your team more than individual ownership.
- Explain the why, just like I do in this article: why it’s important to share knowledge, what issues it can solve in the team, how it can benefit the individuals…
- Give kudos: the goal is not to finger-point who didn’t write a single page of documentation this month and praise the one who wrote a lot, but to not hesitate to thank people when they added something to the wiki, especially when you know it’s not natural for them.
- Lead by example. I really believe that if some people start participating in the effort, the others will see that it’s useful, and over time they will want to help too.
- Help those who need it. It could be by writing a four-hands article, giving feedback…
- Make it a goal (for the yearly objectifs e.g.), if it’s necessary and if you feel it could encourage the person.
- Explicitly encourage the person if they know something useful that could benefit the team: maybe they’re not even aware of it.
- Give time for people to share knowledge. I you’ve never written an article, you probably have no idea how long it takes… Engineers are often under pressure, allow them explicitly to take time for this.
What to share in a wiki?
This is to decide with your team, to ensure consistency and efficiency of the knowledge base (if it grows too big, searches will be less efficient for example), but I would personally encourage those topics:
- Information on the environnements (if in a DevOps team), how are the builds and deployments made, who has what right were, how to access them…
- How to setup one’s development workstation (read more in The hitchhiker’s guide to a great developer onboarding)
- Knowledge specific to the business: what do we develop, for whom, what are their needs, why…
- Software infrastructure, modules, communications between them, technologies
- Recurring bugs and error messages, the ones you encounter regularly when installing some tools or when debugging, anything that had to be explained or searched twice
- Pitfalls of the technologies you use (specific management of the date and time, security issues, weird naming of a service making it hard to understand or find…)
- Conventions and good practices in the team
What we don’t care about in a team wiki:
- Exotic errors, encountered once in a very specific situation and very unlikely to happen again.
- How to get today’s date in JavaScript?
First, stop using JavaScript ffs.This is super easy to find on the Internet and the goal is not to rewrite the documentation of the technologies you use, just stick to functions that are less widely known, or specific implementations. - The beautiful presentation of the business published on the corporate website: we’re looking for quick and easy-to-read documentation that goes straight to the point. The team wiki shouldn’t copy/paste existing content, just add a link if you think some developers will want to read the full story written by the marketing team.
Tools to share knowledge and documentation in the team
I’ll make it short because this really depends on the licenses your team has (usually, you’ll have a contract with a provider and use their solution). I’ve used Confluence (Atlassian) quite much and really like it because it’s pretty complete (it feels like a blog, and I love blogging). Microsoft Teams also has a Wiki for teams that allows to create structured pages, it’s a good solution if you already work a lot in Teams as it doesn’t make you use a new tool. I guess there are other independent tools out there, but as I haven’t used them, I won’t talk about them.
I would on the contrary not advise to use a solution like Sharepoint, as its purpose is to store documents. There are enough tools dedicated to wiki creation, go for it.
One could also say that emails are a good enough solution to share information, just like chat conversations. Well, not at all. Those are good for short, ephemeral information and quick communications. Same for face-to-face explanations. Sometimes, they’re necessary, but they only benefit one person. The given explanation should be transcribed in the wiki for future reference (by the giver or the receiver).
Knowledge sharing also doesn’t replace READMEs and code documentation, as they serve different purposes.
Team documentation good practices
The goal is for the team to use the knowledge base, and to make it usable, we want it to be user friendly (UX, UX everywhere). Here are a few good practices to reach this:
- Use built-in features to make research easier, like tags, labels, categories, but also create a logical structure.
- Check with team members if the tool, the structure, the content… are valuable, adapt based on feedback.
- Create a convention with the team to harmonize the content.
- Use page levels (titles and subtitles), font sizes, colours, images, embedded videos…
- Check what exists and update if necessary, avoid redundancy. Knowledge sharing tools have versioning capabilities, so no one should be afraid to overwrite what’s existing.
- Avoid anything unnecessary, remove outdated content, so the searches only give useful results.
