Notion is definitively a tremendous knowledge-management system. We use it at Packmind (~10 people) for many use cases:
- Technical documentation: how to deploy our IDE plugins to their marketplace, brainstorming and writing solutions for a problem we have to solve, ... any content that could be useful later.
- Marketing / Business: drafts of our blog posts, editorial planning, sales process, personas, ...
- Human resources: Onboarding guides, job interviews management,...
My point here is not to convince you Notion is helpful for your daily work; just try it and make your opinion.
However, some technical documentation for software developers is not entirely satisfying: documentation about coding standards and best practices.
How do teams use Notion to record their best practices?
Most of the teams we met are in one of these two scenarios:
- They don’t have any process to manage their best practices, so they’re barely defined informally.
- They try to centralize documentation on their best coding practices in Notion (or a similar tool like Confluence).
In the second scenario, the most observed pattern is a group of technical leaders that invest time and energy to write best practices in Notion and structure them according to some topics. Then, developers in the organization are expected to read this content when they need it.
In practice, this process meets several pitfalls.
#1 - Humans need context to restore knowledge
Starting from a blank page does not really help developers to identify which best coding practices are relevant to record. It’s easier to extract that content from our source code, directly from our IDE. It gets tedious as we need to switch back and forth from our IDE to Notion.
Plus, only a few people are concerned with feeding Notion with best practices. It may create a climate where developers don’t feel involved or, more generally, involved on the code quality topic. That concentrates the burden of the work on a few people, and others can feel excluded.
#2 - Content can get quickly outdated
We know that keeping documentation up-to-date is a major challenge for tech teams. Mainly because this is not something developers love to do but “need” to do. In high-pressure projects, such tasks are skipped and are likely to be forgotten.
Developers putting best practices documentation in Notion usually do it as a one-shot process after several days of working on that task. A few months later, they’re seldom come back to this documentation to review if it’s relevant or not, and we may start to observe outdated content in our wiki.
#3 - Few consultations due to lack of integrations
How many times did we hear this sentence:
“We’ve got a Wiki, but nobody reads it.”
In other words, a lot of people are not aware of the content you’ve created. In fact, this directly impacts problem #2 above because when you feel that a majority of people do not care about the work you’ve accomplished, you’ll lack the motivation to invest more time in this activity.
Actually, people are not judging the quality of your documentation. You’ve probably made it clean, and we can’t doubt that you did your best to make it clear and understandable. However, most developers spend most of their time on their IDE and coding platform (GitHub, GitLab, ...), and that’s where the main pitfall of wikis stands: they lack integrations in the developer ecosystem.
As Notion is a generic knowledge management system, we can’t blame the tool for that. As we said, for some technical documentation, this does the job perfectly. But we have to admit there is a gap to fill in this context. As a consequence, knowledge spreading is laborious when it comes to best coding practices.
An alternative: Packmind
Our goal at Packmind is to overcome that challenge, as we created a collaborative platform to connect developers’ knowledge, designed to define and share best coding practices. We bring innovation in 4 points:
- We developed extensions for IDE and Web browsers to easily identify best practices in their code (applied or not) and suggest them to their team. They can capitalize on code review comments, for instance.
- Teams regularly meet for a Craft Workshop to review developers’ contributions, discuss them, and either validate, reject, or run a battle. The knowledge base increases and everyone sees new practices added inside it.
- Thanks to examples and counter-examples of practices in Packmind, it provides suggestions to developers in their IDE and during a code review.
As opposed to Notion, Packmind is a bi-directional process for knowledge sharing: developers feed the knowledge base with best practices documentation, and Packmind helps in return developers with automatic suggestions to assist them in being compliant with the standards in your organization. It does not stand anymore as a static place and everyone is free to contribute.
Want to give it a try? Create your 30-days free trial.
Top comments (0)