On 2024-01-26 11:52, Steve Dondley wrote:
> On most systems,, a user’s zsh configuration files are kept in their $HOME directory by default. If you wish to store these modules in a different location, this can be modified by setting the value of the ZDOTDIR parameter to a directory path of your choosing. For example, if you wish your user to follow the XDG specification, you might set the value to $HOME/.config/zsh. Typically, this value is set in the /some/config/file configuration file but consult your OS’s manual for details.
>
> This is a much gentler way of introducing this variable to me.

You and I have essentially identical ideas about how it should read.  
Even if the manual is to be a manual, not a 'zsh for dummies', the 
language could be much more helpful.  But it's as long as the Bible, and 
who's going to spend a year giving it a workover?

But my main point is that it feels like the documentation makes the
>>> assumption you know how a typical shell works and that you are
>>> familiar with the many common features between the different kinds
>>> of shells.
Yes, it does, and so it must.
>> Your observation is correct. All documentation, including zsh's, must
>> assume some level of prior knowledge. When our understanding doesn't
>> meet this level, it can be challenging and frustrating, but we can
>> bridge this gap through other resources. On the other hand, if the
>> documentation were too basic, covering familiar ground, it would be
>> inefficient for advanced users, leaving them to sift through redundant
>> information.

Yup, so there's the dilemma.  But even then, as Steve's little example 
above shows, within the culture of a manual (not a help resource) things 
could be better.  If it were up to me I'd paste Steve's little edit 
above into the manual -- subject to a close look by the experts of 
course.  The devs have admitted a few changes, but much more could be 
done IMHO.  Things don't have to be terse and obscure.