On Fri, Aug 15, 2025 at 12:10 PM Julia Evans <julia@xxxxxxx> wrote: > > Hi, > > > I somehow find the text before this change easier to understand > > (except for one thing). "If you edit `file.c` after adding it" in > > the new text says the same thing as "if you want subsequent ... in > > the next commit" in the original but in a much better way. > > I really appreciate all of this feedback. It makes me wonder if there would > be a better way to approach this man page. Usually when I'm revising a technical > explanation, I find people who are currently users of the software but who have > trouble understanding how it works. Then I ask them to give feedback on what's > confusing to them about the explanation or what questions they have. > > I do this because I find that often people who are extremely comfortable > with using the software (including me, which is why I usually spend so much > time collecting feedback like this!) can lose sight of what's confusing to an > "average user". The curse of knowledge ;) > And every time I'm part of a discussion about documentation for > an open source project it seems a bit strange to me for a group of people who > all already understand the concept to be discussing what would be clearest to an > "average user": surely the users themselves should be the judge of what's clear > to them! > > I'm still pretty new to writing open source documentation so I don't know if > collecting user feedback like this is a normal part of the process, but I always > learn a lot from this type of feedback and it's pretty easy for me to collect > it. Whether it is or isn't normal, we could probably still benefit from that perspective. As Junio likes to say, a mistake being old is no good reason to carry it forward into the future (or replicate it). I'll take that to mean we also have an opportunity to improve the inputs to documentation (as "leaving out such a perspective" would be the "mistake"—note I'm not ascribing intent, malicious or otherwise!). -- D. Ben Knoble
