Comment by xpe

> Humans are the real audience for documentation.

Seeing "real" is a warning flag here that either-or thinking is in play.

Putting aside hopes and norms, we live in a world now where multiple kinds of agents (human and non-human) are contributing to codebases. They do not contribute equally; they work according to different mechanisms, with different strengths and weaknesses, with different economic and cultural costs.

Recall a lesson from Ralph Waldo Emerson: "a foolish consistency is the hobgoblin of little minds" [1]. Don't cling to the past; pay attention to the now, and do what works. Another way of seeing it: don't force a false equivalence between things that warrant different treatment.

If you find yourself thinking thoughts that do more harm than good (e.g. muddle rather than clarify), attempt to reframe them to better make sense of reality (which has texture and complexity).

Here's my reframing: "Documentation serves different purposes to different agents across different contexts. So plan and execute accordingly."

[1]: https://en.wikipedia.org/wiki/Wikipedia:Emerson_and_Wilde_on...