What docs-as-code means

I think this is a really good point in the post:<p>&gt; 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.<p>While some WYSIWYG cloud-based docs platforms make it easier to make changes, that&#x27;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.<p>And if you&#x27;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.<p>I&#x27;ve even created a company specifically to help with this workflow: <a href="https:&#x2F;&#x2F;www.doctave.com" rel="nofollow">https:&#x2F;&#x2F;www.doctave.com</a><p>Also, lots of comments here seem to be thinking of docstrings and other in-code documentation. I think that&#x27;s really a different category that has a different set of goals and issues. This post is specifically about customer-facing documentation.

Having worked both as a developer and as a technical communicator (for software), I&#x27;m thinking that low friction for developers is paramount, and that therefore the way to get developers to put some effort into it is to have documents both (a) written in Markdown (or adoc or rST or typst) and (b) co-located with code under version control. Change the code, change the docs, no screwing around, BUT a quick &amp; simple brain dump can suffice because of [see next paragraph].<p>To whit: I have yet to hear of a documentation system that provides fully bidirectional updates between such documents-as-code and edits made further downstream along the documentation production pipeline. That is to say, when a TC person or a reviewer makes edits to content, these changes should propagate back to the docs-as-code material.<p>Then everyone benefits, including senior devs whose scarce time is optimised by having TC people expand and polish their hasty scribblings, and junior devs who have well-maintained documentation at-hand in-place.<p>My 0.02€, YMMV. Maybe too niche.

In all my 26 years of working as a software dev, in the ~20 companies that I&#x27;ve worked or consulted for in various countries, never once did I see code documentation work out well.<p>It wasn&#x27;t that the will was not there: in almost every single of the companies the devs and management agreed that good documentation was important. And every now and then some heroic effort would be made to finally clean up Confluence or whatever system was used at the time. And for a little while that would work, then slowly documentation would become neglected here and there, and in the end it would become so bad that nobody would use it anymore. Except perhaps to showcase your commitment to best dev practices to your manager when it was time for your performance review.<p>It doesn&#x27;t matter if documentation has to be added in the code, or to some external system or both. Sooner or later it will be neglected, become out of sync and eventually become worse than no documentation at all.<p>With the exception of external libraries or API&#x27;s, software simply changes too fast. You&#x27;d need an army of technical writers to keep all documentation in sync. And unlike what the author writes, I have actually been working for a couple of companies that gave up and simply used the code as documentation, and surprisingly this worked out pretty well.

The problem with &quot;documentation&quot; in commercial code is that nobody reads it.<p>Any &quot;documentation&quot; that isn&#x27;t embedded in code will never be opened again.<p>Any &quot;documentation&quot; in the form of doc-strings and comments will, over time, lie.<p>This is because competent programmers cannot agree on whether to even comment.<p>When any large percentage of competent programmers do not comment, it is better to not rely on comments.<p>Here&#x27;s another pitch:<p><pre><code> Code-as-Docs</code></pre>

Doing docs-as-code by putting documentation in the codebase is somewhat of an oversimplification.<p>Usually, you want to use feature flags to decouple changes in Product from Engineering-driven deployments, so that new feature work can be rolled out slowly and its impact on KPIs measured, and so that engineering can de-risk the delivery of large changes by putting those changes behind feature flags with 0% rollout.<p>The problem is, documentation is <i>much</i> closer to Product than Engineering, meaning, doing docs-as-code correctly means putting your documentation behind the same feature flags. So you should have both a public static site that shows the documentation for features whose flags have 100% rollout, plus your application itself should <i>also</i> show the documentation, so that you can show the documentation to users for feature flags enabled for those users.<p>There aren&#x27;t really any frameworks that have this docs-coupled-to-feature-flags pattern available off-the-shelf and most companies don&#x27;t consider it high-enough priority to build in-house.

I was thinking this might have been a treatise on prompt engineering, or something like Rational Rose.<p>I was actually pleasantly disappointed. I am glad to see documentation treated as a &quot;first class&quot; engineering Discipline. I would say the same goes to creative authors, such as graphic designers, or 3D modelers.<p>I&#x27;m fairly big on good documentation[0], myself, and feel its absence, whenever I look at most codebases, these days.<p><i>&gt; Documentation is vital software infrastructure</i><p>Definitely agree. I am feeling the decline in Apple&#x27;s documentation (I&#x27;m an old-time Apple app developer, and remember <i>Inside Macintosh</i>). It&#x27;s gotten <i>absolutely awful</i>, these days. I&#x27;m just starting on a SwiftUI app (I think I may have finally found a good application for it), and, boy howdy, is that documentation ... <i>less than ideal</i>.<p>Fortunately, someone else thinks similarly, and did something about it[1]. I hate to rely on these types of things, because they often lose sync with the subject, but it is totally necessary.<p>[0] <a href="https:&#x2F;&#x2F;littlegreenviper.com&#x2F;leaving-a-legacy&#x2F;" rel="nofollow">https:&#x2F;&#x2F;littlegreenviper.com&#x2F;leaving-a-legacy&#x2F;</a><p>[1] <a href="https:&#x2F;&#x2F;swiftui-lab.com" rel="nofollow">https:&#x2F;&#x2F;swiftui-lab.com</a>

This article is awesome and resonates with my experience! I used to work for one of the big cloud vendors. We frequently had doc writers in our sync calls. Quite frankly, they never had a chance! Much of our documentation, our errors, status codes etc. was burried in the code and we (developers) were simply to busy to work effectively with technical writers.<p>Don&#x27;t get me wrong here. Where I say &quot;busy&quot; I don&#x27;t mean their work wasn&#x27;t important (it was!) but we had our own projects and jumping on a call to improve errors messages is not too exciting for most of us - and it&#x27;s not the stuff that drives promotions. As a develper it&#x27;s simply to easy to gatekeep code.<p>Now follows a shameless plug: I&#x27;d be so excited to hear your opinion about a tool I&#x27;m building. It&#x27;s called <a href="https:&#x2F;&#x2F;api-fiddle.com" rel="nofollow">https:&#x2F;&#x2F;api-fiddle.com</a>. Conceptually, it should help developers work API-first instead of code-first. It&#x27;s great for devs because it makes the work faster and safer. BUT, an added benefit is that API docs are no longer burried in code and technical writers have a nice interface to contribute to them (and hold devs accountable!).

Love the theme of your blog

So, I feel like &quot;Docs-as-Code&quot; has some context I&#x27;m missing, so I&#x27;m going to comment on docs in general.<p>I think there multiple kinds of docs for software.<p>* Comments explaining a specific section of code.<p>* API docs describing functions&#x2F;classes&#x2F;etc.<p>* Docs on how to use a library&#x2F;class&#x2F;etc. Usually including simple, isolated, examples.<p>* Tutorials on how to create simplified applications using the developed tools.<p>* Docs on how to deploy, configure, and maintain an application.<p>* Docs on how to use an application.<p>* Docs on how to troubleshoot an application.<p>* Docs on how to integrate applications.<p>* And likely others I&#x27;m missing.<p>Personally, I&#x27;ve been seriously frustrated by how bad most of the open source (haven&#x27;t done much with proprietary code) documentation is. Case in point is Drupal and Symfony. Trying to use api.drupal.org is not fun, and Symfony&#x27;s docs always cover the basics, and then there&#x27;s nothing on pulling everything together into something complicated. So you try to dig into the actual code, and end up finding multiple layers of uncommented abstractions. Yes, I can eventually figure out what is going on if I put the effort in, but that&#x27;s a lot of time that could be save by a few lines of comments.<p>I usually end up asking JetBrains AI about what I need, then use what it says after I fix the errors it makes... It&#x27;s also very good at summarizing everything I&#x27;d find if I used a normal search. But that all only works if others have already asked and answered my questions.<p>Some things I&#x27;ve been trying to do to improve my own code&#x27;s documentation:<p>* Unless the line is super obvious, even if I think it is obvious, I try to leave a comment. Yes, it seems pointless, but I have gone back to old code I remember being obvious without said comment enough times that I think it is worth it.<p>* Avoiding &quot;elegance&quot; in favor of &quot;explicitness&quot;. For example, I use full `if` statements instead of ternary operators even when ternary operators would look better. For whatever reason the syntax of ternary operators has never sunk in for me, and the explicitness of `if` is much easier to parse. I also use very descriptive function and variable names. Basically, if I have to think about what something means, I try to change it so I don&#x27;t have to.<p>* Split out functions into smaller functions as much as I can&#x27;t. This means I can use descriptive function names. And I&#x27;m pretty sure it&#x27;s just good practice.<p>I also have been trying to figure out ways to keep higher level docs closer to my code. I have some ideas, but haven&#x27;t tried them yet. Has anyone ever written something that detects changes to a method&#x2F;function, and then when you save your file it pops up asking if related docs need updating? Maybe add comments to the method pointing to where related docs live, and then your IDE&#x2F;tool uses that to know what docs need updating?

This feels like a job ripe for startup disruption.<p>LLM documentation generators tend to benefit from context, and nothing provides better context than a mostly functional code base. The best part is the code doesn’t even need to compile for the LLM to build the context needed.

With LLMs it is now quite easy to generate docs as needed. In fact we built a service to do just that - <a href="https:&#x2F;&#x2F;docs.codes&#x2F;" rel="nofollow">https:&#x2F;&#x2F;docs.codes&#x2F;</a><p>Here is an example of how it is very useful especially for newer libraries.