Hacker News Reader

Comment by nunez | Hacker News Reader

This is facts. All of this talk about putting agent skills directly into repos (as Markdown!) is maddening. "Where were LITERALLY ALL OF YOU whenever the topic of docs as code came up?"

This is doubly maddening with NotebookLMs. They are becoming single sources of knowledge for large domains, which is great (except you can't just read the sources, which is very "We will read the Bible to you" energy), but, in the past, this knowledge would've been all over SharePoint, Slack, Google Drive, Confluence, etc.

View on HN

I've chose to embrace the silver lining where there is now business backing to prioritize all the devx/documentation work because it's easier to quantify the "value" because LLM sessions provide a much larger sample size than inconsistent new hire onboarding (which was also a one-time process, instead of per session).

I do think people are going way overboard with markdown though, and that'll be the new documentation debt. Needs to be relatively high level and pointers, not duplicate details; agents can parse code at scale much faster than humans.

> Where were LITERALLY ALL OF YOU whenever the topic of docs as code came up?

Docs as code is still writing and not coding. Those are simply different skills. As programmers, we find coding to be fun and glamorous and writing to be difficult. Emotionally, it's much easier to finish a piece of code and feel genuinely happy with it (you are proud of your achievement) than it is to write a paragraph of docs and feel genuinely happy with it (you can feel in your bones that it's not good but you don't know how to improve it and you just want it over with). We have not built anywhere near the level of skill for writing than we did for coding when we wrote our own little programs for ourselves and never built a habit of thinking about how other people would interact with our code.

(For me, this is exacerbated by having been more isolated from other people than the average population, partly due to neurodivergence and partly because the hobby was niche at the time, and I assume this is also true of a lot of people currently employed as professional programmers.)

Haha indeed. At work suddenly documentation and APIs are important, but it's all for/behind "skills". Before it was always "sure, that would be nice"...

I do welcome the improvements to doc and APIs this brings though!

Reply on news.ycombinator.com