Technical Documentation in Code vs in Notion
Notion gives our company an “all-in-one” centralized knowledge base for our team’s projects, however, the most programmers like using
[README.md](http://readme.md) files and other documents within their code repository to document their work. The article describes how we were able to consolidate these two approaches.
Benefits of Documentation in Code
- Easier to access/discover documentation while developing
- Easier to keep documentation up-to-date when changes are made
- Documents are version controlled
- Can use frameworks automatically generate documents by reading the code and comments
Benefits of Notion
- Documentation not centralized instead of being dispersed across repositories
- Code and technical documents are together
- Searching across multiple repositories is not easy
- Makes it easy for non-technical users access documents
Luckily there is a solution that has the best of both worlds. We have documentation within the repository that is also synced to Notion every time we merge new code. Notion does not have this kind of integration, so we built a command-line tool called git-notion. git-notion can be run as part of your team’s CI so your technical docs are pushed to notion ever time they are updated. This allows our programmers to write extensive documents within the repository and have it automatically loaded into notion with the rest of their team’s documents so Notion can remain our team’s centralized knowledge base. See the git-notion‘s Github README for usage instruction.