Prove You Care (Write the Docs)

For better or worse, other-than-human-authored code looks here to stay. Personally, I'm okay using and even creating software whose code was written by LLMs. Programming languages, by their very nature, are intended for computer consumption.1 So there's a certain level of appositeness in code written for and by computers.

Moreover, code can be measured and tested objectively. You can define an arbitrary target—functionality, performance, correctness—and generally determine whether a program meets it or not.2 Code does have characteristics that are harder to measure—beauty, elegance, style—but those are generally secondary to whether the program performs correctly.

Documentation inverts this. It has some attributes that can be measured more easily, such as coverage or being up to date. But the most important part of documentation is communicating ideas effectively, and that's a lot harder to measure.

Documentation is also still intended for human consumption. Maybe a function docstring can get by purely stating the facts, but a project README needs to provide context, build trust, and educate. All while guessing the reader's background and state of mind. Today's frontier models can produce passable writing, but still will veer into dense, jargon-filled tangents at a moment's notice, and they do a poor job of understanding a potential reader's mindset and providing appropriate context.

When an LLM writes your documentation wholesale, you're signaling that you don't care about the humans on the other end. You don't care about communicating ideas to them effectively. You don't value their time and effort.

If you want some human engagement, put in some human effort.

  1. Programming languages are, of course, also intended for human consumption. But that's more a byproduct of necessity during program creation rather than its inherent purpose.

  2. It's not always easy though!