> 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.
> you probably want your docs updates to be coordinated with your product releases
People keep saying that but I can't help to wonder if they're every on the receiving end of documentation.
Documentation isn't code. It may all be text, and share other similarities, but it's something fundamentally different. You can't substitute code for docs, or docs for code. The above reasoning is what ends up publishing /docs/5.3/chapter1/installing.html. Reading documentation for a specific version of the product is not desirable.
To understand the product, it's very relevant what happens in version 5.4, and I should not have to diff different releases of the docs to find out. The documentation should say clearly that this function will be deprecated, or look different in the next version. In short, documentation should neither be branched with code, nor released with it. It should live in parallel and describe not only how the product works, but more importantly why it works like it does.
Your product looks really interesting. I'm a big advocate for docs-as-code at my company. We use Confluence generally, but our team uses GitLab and Gatsby for our documentation/blogs as we really value the Merge Request workflow.
Our biggest challenge is local development. A WYSIWYG is just so useful in that regard. Is that what Doctave Studio is trying to solve?
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.
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.
To me, there are three places that dev-generated documentation can live:
1. The code
2. The issue tracker
3. The version control system
A small amount of exceptionally useful and frequently referred to documentation like the process for setting up a new dev environment or some complex support task can live elsewhere.
Otherwise, I think the top down imposition of a documentation culture is unlikely to succeed.
The real secret to getting a team that has a shared understanding of the system, the business, and each other is to retain your developers. A team that's been together for five years has superpowers no amount of documentation can replicate.
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.
> 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.