You're correct - Doctave Studio is for making local development easier. It packages the whole "authoring environment", so it's all you need to start writing.
It's technically not WYSIWYG, but you do get a side-by-side real-time preview of your rendered Markdown content and OpenAPI specs that update as you type.
You get autocomplete, broken links checking, etc. Everything you'd expect from an editor.
> 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.
I've even created a company specifically to help with this workflow: https://www.doctave.com
Also, lots of comments here seem to be thinking of docstrings and other in-code documentation. I think that's really a different category that has a different set of goals and issues. This post is specifically about customer-facing documentation.
I also want to give a shout out to the Rustler folks for creating a great library! We use Rustler quite extensively at Doctave, and have written about our experiences with Rustler before [0] (though our architecture has advanced quite a bit since the article was written).
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.
For us at Doctave (https://www.doctave.com), migrating customers from existing solutions manually ourselves has proved very effective.
The product is a technical documentation platform, and most customers are coming from an existing solution - be it an open source static site generator or CMS of some sort. The pain of migrating is usually a big factor keeping teams in their existing setup, and doing the migration for them eliminates a common objection.
We'll likely keep doing this even as we grow, but right now we tend to offer this service regardless of the size of the customer. The combination of great customer service and everything we learn while migrating the existing content makes it worthwhile.
Agreed on a lot of this, but I'd be cautious about saying that any kind of documentation is "simple". Especially when it comes to technical products - be they internal or external.
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.
Congrats on the launch! I'm curious how you manage syncing the changes from the WYSIWYG editor back to the repo?
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.
There is also https://www.doctave.com which is a dedicated host for Doctave documentation sites. It's aimed at teams that want to do docs-as-code, but still want to have all their docs centralized and searchable under one roof. This is closer to GitBook.com, but Doctave still uses a docs-as-code approach instead of GitBook, which is mostly used through a WYSIWYG editor and is closer to a traditional knowledge base system.
Author here. This is a good point. In this case we found it does slow down clean builds somewhat since we're pulling down + compiling Rust dependencies now as well as Elixir. While actually editing Elixir code I haven't experienced any noticeable slowdown for incremental builds - the Rust code is mostly static.
Author here. I actually was not aware of cmark.ex - thanks for pointing it out.
In this case the code reuse was more important than pure native speed. We already had a Rust library that used pulldown-cmark [1] with some custom tweaks that we wanted to duplicate. Maybe this behavior could have been copied using cmark.ex too (we thought about doing this in pure Elixir, as mentioned in the post), but given how straightforward Rustler made integrating our existing code, this seems like the better choice.
It's technically not WYSIWYG, but you do get a side-by-side real-time preview of your rendered Markdown content and OpenAPI specs that update as you type.
You get autocomplete, broken links checking, etc. Everything you'd expect from an editor.