> The most underrated skill to learn as an engineer is how to document. Fuck, someone please teach me how to write good documentation. Seriously, if there’s any recommendations, I’d seriously pay for a course (like probably a lot of money, maybe 1k for a course if it guaranteed that I could write good docs.)

Good docs are docs that make it easy to implement the next feature.

From an AI perspective, it's my observation that LLMs often write code with lower quantity / quality docs. At the same time, they are reasonably good at synthesizing / inferring meaning from code that lacks good docs. They often do so internally by forming a chain of thought / reasoning around how the code works. The docs that should be written as part of the code are probably the same things that an LLM would reasonably come to by spending tokens when modifying that code. I believe that this should be trained into model so that future LLM work starts with not having to build up context.

In the absence of that being built in, something I've been experimenting a little with is tuning what I want to see in docs that actually help source control / development. Currently that's at https://github.com/joshka/skills/tree/main/doc-steward - still needs a bunch of work, but it's generally better than nothing. YMMV