News for hackers. Stuff that matters.
Re:What Docs-as-Code Means by NiklasBegley on Sunday October 20, 2024 @10:33AM (#41895615)
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.

Re:What Docs-as-Code Means by robertlagrant on Sunday October 20, 2024 @04:00PM (#41898070)
> And if you're an engineering lead company,

Nit: engineering-led

Re:What Docs-as-Code Means by zelphirkalt on Monday October 21, 2024 @07:43AM (#41903070)
A small change in writing, a big change in meaning.
Re:What Docs-as-Code Means by NiklasBegley on Monday October 21, 2024 @09:14AM (#41903829)
Oops. Good catch.
Re:What Docs-as-Code Means by tikkabhuna on Monday October 21, 2024 @08:38AM (#41903523)
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?

Re:What Docs-as-Code Means by NiklasBegley on Monday October 21, 2024 @09:18AM (#41903866)
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.

Re:What Docs-as-Code Means by xorcist on Monday October 21, 2024 @06:49PM (#41909377)
> 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.