Notation

Notation

Documentation tooling for engineers

68 followers

Visit website
•
•
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.
Notation gallery image
Free
Launch tags:Writing•Developer Tools•GitHub
Launch Team / Built With
AssemblyAI
AssemblyAI
Build voice AI apps with a single API
Promoted

What do you think? …

Kristian Gaylord
Notation
Maker
📌
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.
Adam Szokalski
Cool. Gonna try it out in my projects!
Kristian Gaylord
Notation
Maker
@aszokalski Thank you, Adam! :D Please let me know how I can support. Feel free to file an issue in Github if anything seems out of place.
Kyrylo Silin
Telebugs
Hey Kristian, How does Notation handle conflicts if multiple team members are updating docs simultaneously? Are there plans to support other platforms besides Notion in the future? Congrats on the launch!
Kristian Gaylord
Notation
Maker
@kyrylosilin Thank you for these questions! > How does Notation handle conflicts if multiple team members are updating docs simultaneously? My intention is that there should never be simultaneous edits. Consider this workflow: 1. Engineer writes documentation on branch. 2. Branch gets merged into master 3. `notation ship --src docs/` gets run as part of a Github Action. This automated CI for documentation prevents simultaneous edits. Users (in my view of the world, at least) should not be manually editing these Notion pages otherwise. The repo is the source of truth and Notion should reflect that truth based on normal engineering release processes. > Are there plans to support other platforms besides Notion in the future? Yes, if people think this is an interesting enough tool I'm considering turning into into a more full-featured platform that just hosts the static site for you but allows for a lot more customization and control. What platforms would you like supported?
dashuai
Loving the focus on seamless integration with Notion, @kayolord! The design philosophy really resonates with how documentation should be part of the development process, not a separate entity. The emphasis on Markdown as the only front-end framework simplifies things so much. We're often bogged down by complex setups and tools that can take away from actual coding. Searchability is critical too—you're spot on that a good search feature can save so much time! It’s great to see a product that not only prioritizes accessibility for non-engineers but also keeps everything under one roof for those who are. Can’t wait to see how Notation evolves further; I'm definitely considering it for my next project! Upvoted!
Toshit Garg
Congrats for launch of Notation....
Rodney J. Belcher
This looks like a really useful tool for keeping documentation organized and accessible. I appreciate the focus on simplicity and integration.