Notation allows you to write markdown and automatically publish it Notion. Once it's in Notion, it can be internal, password protected, personal, or you can ship it as a public website. You also get all of Notion's AI, search, and formatting for free.
Design Philosophy
1 — Documentation should not be managed separately from the repo.
Documentation describes code. It should live with the code, have dinner with the code, go to bed with the code, and get up in the morning with the code.
2 — I should not have to login to some separate service to update docs after I merge and deploy code.
That's hard to keep track of. Engineers cannot be trusted to workout outside the repo. Online documentation tools give me JIRA vibes. No thank youuu.
3 — The only frontend framework I want to think about is Markdown.
Docusaurus is an interesting product but it's too complicated. I do not want to wrestle with React. I do not want to deploy a website.
4 — Some people are not engineers. They should be able to read my docs.
Users, product mommies, etc.
5 — Docs should be highly searchable.
Good search is a hard problem so better let someone else worry about that.
6 — Documentation should be subject to the same review & CI process as code.
See point 2.
Kristian Gaylord