Being short and concise is usually the better way.

I tend to be too verbose in writing as I want to explain the context in more detail, but short, accurate, concise is best. Many developers fail at that too, though. Many projects do not have working examples. That annoys me the most. It sends a message of "I don't care about new users learning how to use my project".

>"I don't care about new users learning how to use my project"

I published something the other day with minimal instructions, and felt briefly conflicted.

But I figured, if you want to run it, you'll find a way! (It probably doesn't even work on other operating systems, but porting it would take what, 20 seconds of Codexing?) It was true before AI, and it's definitely true now.

My intended audience is people who want to get their hands dirty. Though I suppose these days, that's the machine's job...

Same for me. What helped is the realization that I was trying to cater to everyone in the same document. Now I try to follow the organization outlined in https://diataxis.fr/ I’m still very bad at documentation in general but I’m less dissatisfied when I come back a few months later.

> Being short and concise is usually the better way.

The golang docs are like this. As a novice, you are looking for detailed prose, but as you progress, you come to appreciate the terseness.