NiklasBegley

> If you don’t review, check, and merge docs the same way your org reviews, checks, and merges code, you’re not doing docs-as-code — you’re doing docs-as-bore.

While some WYSIWYG cloud-based docs platforms make it easier to make changes, that's not necessarily what you want. Docs are a critical component of how your users perceive your product - you want to have checks that it meets certain quality and accuracy standards. Just like your code.

And if you're an engineering lead company, you probably want your docs updates to be coordinated with your product releases. Git is just the logical place to put your docs in that case.

Integrating Elixir and Rust has been delightfully straightforward and is a great choice for calling into libraries not available in Elixir, or offloading CPU intensive tasks.

Technical writers train specifically to communicate complex technical topics to readers, and it's not an easy job. It requires understanding your readers, what kind of backgrounds they have, and what are they trying to achieve. This becomes especially important for documentation that is meant for your customers, where very real revenue depends on the quality of your docs.

I'm a bit biased since I'm the founder of a documentation startup [0], but tools also do play a big part. Devs often tend to enjoy writing something Markdown next to their code than going to an old wiki like Confluence that's disconnected from the engineering cycle. Choosing the right tool lowers the barrier to keeping the docs up to date.

If you have two editors, one editing raw Markdown, and another one comes along with the WYSIWYG editor and makes a change in a new commit, how is that change handled? Is the original formatting preserved, with only the new changes injected into the document?

I ask since I've thought about this a lot for my own company[0], and this is a surprisingly tricky thing to pull off.

You usually end up losing all formatting information once a WYSIWYG editor comes in unless you do something clever, leading to very strange diffs.

The Doctave CLI is more like MkDocs or Docusaurus in that it supports a docs-as-code workflow. It takes your Markdown files and generates a pretty documentation site from them. It's more batteries-included and opinionated though: it has limited customizability by design, so that you don't have to wrestle with plugins or spend time bikeshedding themes. You just install Doctave (a static binary), write your docs, and host the site on e.g. GitHub Pages.