[doug_durham]

If find your comment "AI Slop" in reference to technical documentation to strange. It isn't a choice between finely crafted prose versus banal text. It's documentation that exists versus documentation that doesn't exist. Or documentation that is hopelessly out of date. In my experience LLMs do a wonderful job in translating from code to documentation. It even does a good job inferring the reason for design decisions. I'm all in on LLM generated technical documentation. If I want well written prose I'll read literature.

[petetnt]

Documentation is not just translating code to text - I don't doubt that LLMs are wonderful at that: that's what they understand. They don't understand users though, and that's what separates a great documentation writer from someone who documents.

[doug_durham]

Great technical documentation rarely gets written. You can tell the LLM the audience they are targeting and it will do a reasonable job. I truly appreciate technical writers, and hold great ones in special esteem. We live in a world where the market doesn't value this.

[skydhash]

The market value good documentation. Anything critical and commonly used is pretty well documented (linux, databases, software like Adobe's,...). You can see how many books/articles have been written about those systems.

[sourdoughness]

We’re not talking about AI writing books about the systems, though. We’re talking about going from an undocumented codebase to a decently documented one, or one with 50% coverage going to 100%.

Those orgs that value high-quality documentation won’t have undocumented codebases to begin with.

And let’s face it, like writing code, writing docs does have a lot of repetitive, boring, boilerplate work, which I bet is exactly why it doesn’t get done. If an LLM is filling out your API schema docs, then you get to spend more time on the stuff that’s actually interesting.

[skydhash]

A much better options is to use docstrings[0] and a tool like doxygen to extract an API reference. Domain explanations and architecture can be compiled later from design and feature docs.

A good example of the kind of result is something like the Laravel documentation[1] and its associated API reference[2]. I don't believe AI can help with this.

[0]: https://en.wikipedia.org/wiki/Docstring

[1]: https://laravel.com/docs/12.x

[2]: https://api.laravel.com/docs/12.x/

[Cthulhu_]

> Anything critical and commonly used is pretty well documented

I'd argue the vast majority of software development is neither critical nor commonly used. Anecdotal, but I've written documentation and never got any feedback on it (whether it's good or bad), which implies it's not read or the quality doesn't matter.

[skydhash]

Sometimes the code, if written cleanly, is trivial enough for anyone with a foundation in the domain so it can act like the documentation. And sometimes, only the usage is important, not the implementation (manual pages). And some other times, the documentation are the sandards (file formats and communication protocols). So I can get why no one took the effort to compile a documentation manual.

[wonger_]

Well documented meaning high quality, or well documented meaning high coverage?

[ayrtondesozzla]

> If I want well written prose I'll read literature.

Actually if you want well-written prose you'll read AI slop there too. I saw people comparing their "vibe writing" workflows for their "books" on here the other day. Nothing is to be spared, apparently

[Cthulhu_]

A lot (I'd argue most of it) of literature written by humans is garbage.