Notation

Documentation tooling for engineers

66 followers

Documentation tooling for engineers

66 followers

Visit website

Team collaboration software

•

Knowledge base software

•

Static site generators

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.

Free

Launch tags:Writing•Developer Tools•GitHub

Launch Team / Built With

CloudflareYour next app belongs on Cloudflare Workers. Deploy for free

Promoted

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.

Report

2yr ago

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!

Report

2yr ago

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?

Report

2yr ago

Cool. Gonna try it out in my projects!

Report

2yr ago

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.

Report

2yr ago

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!

Report

2yr ago

Congrats for launch of Notation....

Report

2yr ago

Reviews