Notion is definitively a tremendous knowledge-management system. We use it at Promyze (~10 people) for many use cases:
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.
Most of the teams we met are in one of these two scenarios:
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.
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.
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.
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.
Our goal at Promyze 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:
As opposed to Notion, Promyze is a bi-directional process for knowledge sharing: developers feed the knowledge base with best practices documentation, and Promyze 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.
Promyze, the collaborative platform dedicated to improve developers’ skills through best practices sharing and definition