Don’t let your best coding practices die in a wiki
In software engineering organizations, there’s this challenge to define, record and spread best coding practices and standards across teams. This brings consistency to source code and improves its maintainability. It also avoids bottlenecks and endless discussions during code reviews on a given coding practice.
A common approach to this challenge is building a knowledge base in a Wiki-like tool, such as Confluence or Notion.
Although the idea makes sense and is relevant, at Packmind, we’ve talked with companies that shared the pitfalls and drawbacks of this approach for managing their coding standards.
We discuss them in this post.
There are 2 details here that reflect the pitfalls of most wikis: The “TODO” section and the “Last update” property.
Keeping an up-to-date wiki requires energy and effort from a group of people (mainly technical leaders). Most of the job is often achieved when bootstrapping the process since there is a solid motivation to build a knowledge base of coding practices.
But this motivation tends to lower after several months, mainly because:
If not, they won’t search for it. It’s common that engineers looking for answers to their questions receive as answer a link to the appropriate Wiki page because they’ll be more likely to directly ask their colleagues instead of searching in the knowledge base.
Coding practice shouldn’t be built independently by a small group of engineers without collaboration and discussion with others engineers. Think about how best practices are shared once written down in a Wiki. If a developer receives a message saying:
Coding practice shouldn’t be built independently by a small group of engineers without collaboration and discussion with others engineers. Think about how best practices are shared once written down in a Wiki.
If a developer receives a message saying:
Raising and maintaining the practices repository is complex
The most observed pattern can be summarized with the following picture:
There are 2 details here that reflect the pitfalls of most wikis: The “TODO” section and the “Last update” property.
Keeping an up-to-date wiki requires energy and effort from a group of people (mainly technical leaders). Most of the job is often achieved when bootstrapping the process since there is a solid motivation to build a knowledge base of coding practices.
But this motivation tends to lower after several months, mainly because:
- It takes time to identify and raise the practices, write them, and find the appropriate positive and negative examples (Do/Don’t);
- This feeling that content gets a few hits and engagement from other developers (so why should I continue?)
Engaging engineers is too neglected
Knowledge has value only if it’s shared and understood by others. But having great content in your Wiki does not guarantee that people will interact with it. Do they even know it exists?
If not, they won’t search for it. It’s common that engineers looking for answers to their questions receive as answer a link to the appropriate Wiki page because they’ll be more likely to directly ask their colleagues instead of searching in the knowledge base.
Coding practice shouldn’t be built independently by a small group of engineers without collaboration and discussion with others engineers. Think about how best practices are shared once written down in a Wiki. If a developer receives a message saying:
Coding practice shouldn’t be built independently by a small group of engineers without collaboration and discussion with others engineers. Think about how best practices are shared once written down in a Wiki.
If a developer receives a message saying:
Hey, I’ve added new 4 React coding practices to follow in our Wiki. Take a look here!Do you think it’s engaging? We’ve got plenty of stuff to do, and you’ve already decided they’re all valid. So I’ll wait until someone tells me in a future code review that I don’t follow them. What if, instead, the same developers get this:
Hey, I came up with 4 React coding practices that I think could be helpful in our context. I want to introduce them to the team, discuss them, and decide if we validate or discard them. Would you be available for a short 30-min meeting this Friday?More engaging right? Developers feel more involved in the construction process. And maybe they’ll have great suggestions to make!
Static content isn’t appropriate when coding
Developers seldom code in their IDE while interacting with the knowledge base to see if they follow or not a coding standard. Ideally, they need to get the right information when they need it. They should be notified if their code is not compliant with a practice. But Notion or Confluence are not designed for this specific use case. And when coding, we want to stay focused on our IDE. That’s why static should become dynamic instead: how to push a coding practice when it’s relevant? How to create a bi-directional flow between developers and the knowledge base?Create Living Best Coding Practices
If this post reminds you of your current context, you’re likely looking for alternatives to improve how you manage your best practices. Here is one for you. At Packmind, our ambition is to design a dedicated solution to this coding standards-sharing challenge. Our platform allows to:- Raise coding standards from IDE and during code reviews thanks to our extensions;
- Validate them during collective workshops;
- Create a living coding practice by enriching it with patterns (regular expressions, SemGrep patterns, …), and making it available for developers when they write or review source code;
- Support onboarding of new engineers with interactive challenges to learn the current practices in the organization.