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.
replyI started using diataxis for all my docs a while ago and I've never gone back to any other kind of documentation framework. In addition, all docs that do not follow this framework makes me really sweaty.
replyI had diataxis in mind when I wrote my comment. It's an important and excellent guideline on picking the style based on purpose of the doc.
reply>"I don't care about new users learning how to use my project"
replyI 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...
> Being short and concise is usually the better way.
replyThe golang docs are like this. As a novice, you are looking for detailed prose, but as you progress, you come to appreciate the terseness.