| TL;DR: Favorite stack is Notion -> notion-markdown-cms -> VuePress -> netlify So I've gone through a bit of journey doing docs for a product company. I feel that for a product company it's really important to own your documentation and the publishing workflow as it's a key part of your product. GitBooks was my first stab. I liked git and markdown, however I disliked all the places where "proprietary" formatting/features crept in and once it got more closed/commercial wrt. publishing/theming pipeline we went out. We then adopted docusaurus v1 for our product documentation. It's a great tool, but never really built custom components for it because we're not a react shop. We did integrate some nice tools to work with our markdown tool (e.g. markdown-lint, custom code snippet injectors etc). One downside of docusaurus is how much friction there is to create a new page. You have to create a markdown file, insert frontmatter, add it to sidebars.json, reload the dev server, then insert your content. When docusaurus announced v2, we considered adopting it. Instead, we started looking into VuePress vNext. What I love about it is that its configuration is TypeScript (vs. JSON). This allows us to generate things like navbars, sidebars from code instead of manually wrangling JSON. It uses Vite for bundling and the local editing experience is therefore much faster. As you write more and more docs, markdown editing experience becomes important. VSCode + the right plugins can get you far, but we found they all did not feel "fluent" to the point where our team _loves_ writing documentation. People often complained that our company wiki (Notion) feels much nicer, so we built a tool that allows us to use Notion as a "CMS" for our documentation: https://github.com/meshcloud/notion-markdown-cms
It's really handy because that way we get perks like organizing content with databases, link pages using @mention syntax, drag & drop for screenshots etc.
Publishing on netlify rounds it off. |