On 2024-01-26 12:08, Roman Perepelitsa wrote:
> 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?