[NiklasBegley]

I think this is a really good point in the post:

> 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.

[robertlagrant]

> And if you're an engineering lead company,

Nit: engineering-led

[zelphirkalt]

A small change in writing, a big change in meaning.

[NiklasBegley]

Oops. Good catch.

[xorcist]

> 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.

[tikkabhuna]

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?

[NiklasBegley]

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.