Exactly, zsh documentation is a nuclear power station blueprints.Transforming it into a basic physics tutorial
I quite agree. A manual is not a tutorial. Still, that's no
reason for the manual to be impenetrable -- as if that was somehow
a virtue. A while back Peter rewrote something and it went from
being baffling to being helpful. Why *not* make things as clear
as possible?
I agree that your version would be better for someone unfamiliar withthis concept. But can you see that it might be less efficient for
someone who already understands it? And consider where to draw the line with foundational explanations. Should we also explain what $HOME is, what a directory means, or what 'consult' implies?
It's always a matter of judgement where one draws the line. It goes without saying that things should not be dumbed down to the point of dilution. Within, say, a thousand words, why not make those thousand words as clear as they can be? Steve's sample -- what is *lost*? What utility is compromised? If much is gained and nothing is lost, I say it's a plain improvement. Put it this way: if my needs and your needs are in conflict as to the manual, yours must prevail. But what if my needs could be met without compromising yours?