The “Knowledge Sharing” Problem
In my projects, I often try to be a major wiki contributor. I learned some lessons and practices and I see value in sharing them.
The core problem is “Knowledge Sharing”. It is more common in big companies with complex infrastructure and projects. Documentation is my solution of choice and I will focus on it here. But there are other options:
- Knowledge can be shared on 1on1 sessions or group workshops.
- Code reviews, preferably from multiple peers
- Automated tests are easy to read and can serve as documentation
- Code areas or whole repositories can have informal “owners”. It is the owners responsibility to answer questions regarding his area of responsibility. The owner can answer those questions with documentation or verbally, his call. Example — as QA I am responsible for tests and test infrastructure in my project. A problem with legacy code is that maybe the original owners left and there is no owner. If that is the case, maybe a good idea is to appoint one.
- For large code bases it is perfectly normal to have a team of owners. For dependencies that team of owners can be composed of members of affected teams. To combat the tribalism problem it is absolutely essential to educate people that this is an actual team. In big companies it is perfectly normal to be part of multiple such ownership teams — the team of the project, the qa team, the wiki team, the forums social team, etc — and juggle responsibilities.
- Documentation is not just for newcomers. In 3 months we forget key details of our work. I write notes for myself and turning them into wikis is just easy and cheap value
- When you carefully explain your thoughts in docs, you structure your mind and understand the matter and related problems hella lot better. And then people could ask you questions you haven’t even thought about.
- Knowledge is usually distributed between engineers. 1) You cannot have dedicated people responsible for the documentation 2) Internal docs must be written by the people with the actual knowledge, the engineers, and not tech writers. Tech writers are awesome, but their optimal role is of editors and language supervisors.
- Documentation should be super short concentrated knowledge essence, ideally short wikis and guides, not formal. Avoid harmful walls of text that no-one reads. If people are in a situation where documentation amount is an implicit or explicit metric on their performance, they will produce the bullshit essays with mandatory word count from school.
- Awesome tools like confluence and swagger are awesome
- Documentation is valuable for others, but it is not valuable for yourself in the immediate future. Hence most people have very little incentive to write it. You will often hear “I need documentation” but you will very rarely hear “I need to document this”
- For some people, even good engineers, writing documentation is boring AF. Writing is a skill, you cannot expect everyone to have every skill.
- Good documentation takes time, it is impossible to evaluate its objective value, it is easy to do poorly (walls of redundancy)
- Because of the 3 points above it is completely normal for internal documentation to suck. Every single one of companies I worked for had this issue.
- The same points apply to many other good practices we do — linting, peer reviews, automated tests on CI, all of these take time and have annoying errors. But we see value there, we educate people about that value and we do them anyway. Good wiki, just like these practices, requires education and engagement from everyone, not just management
- Enforcing rules is evil. Policies in a team should be mutually agreed.
- If someone finds writing tedious, he can contribute in the other ways mentioned above
- A good company will have a mechanism where you can applaud others for good work. This adds intrinsic motivation. Everyone (not just managers) should congratulate people that add value for others. Side note — extrinsic motivation is harmful in our field of work.
- The concept of “job security” is evil AF
- Competent people can unintentionally put themselves in a “single bus” situation, wikis help then
On “self documenting code”
- A very good place for tech docs is the code itself — docstrings and comments.
- There is this concept that good code is self documenting. There is truth here, redundant docs is evil. But it is not all flowers.
- My opinion on the quality of my code is inherently subjective. I love my work, I worked really hard on my code, of course it is good. So this concept excuses me to skip comments altogether.
- This concept assumes that people of different skill levels have the same understanding of well written code, which is objectively false.
On “new guy writes”
- The code author may be chasing a hard deadline. Some people are seriously bored by writing. And tech details fade away as time passes. It may be suboptimal, but it is common for code and docs to have different authors.
- When you need key information that is not in wiki, you are forced to spend time researching the topic — you read code, you talk with people and put the pieces back together. At that point you have the freshest knowledge on the topic. You are in the best position to write the missing wiki. This feels unfair. You not only spend effort to research it, but now you need to do the boring stuff? WTF? Unfortunately this is the default way wiki is done.
- When I need help in a new area, my practice is to find the owner and offer an exchange — you explain to me and when I am competent I will write the wiki for you. Both parties win.
- People sometimes use the argument that there is no time to write. I find that to be a weak excuse, generally managers are happy with knowledge sharing and hard deadlines are not so often. I strongly believe that the real problem is that people hate the “new guy writes” situation.
- But if for some absurd reason your company is against knowledge sharing, you already know what to do : )
- “Job Security” — when you accumulate knowledge and you deliberately do not share it, it is much harder for management to fire you. You also fuck your team
- “Single Bus” factor — when you are competent or control obsessed, you take more and more responsibilities and when that spirals out of control, you are overloaded with critical tasks that no-one else can do, no time to share the knowledge, everything is urgent, no time for day off, burnout and undeserved contempt for company and team.