Re: Most minimal configuration challenge

[Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>]

Ray Andrews wrote on Fri, Sep 02, 2022 at 07:26:54 -0700:
> On 2022-09-02 03:36, Daniel Shahaf wrote:
> 
> Ironically this sentence would be the perfect start to some doc about
> zstyle that was actually helpful:
> 
> > There's no easy way to explain zstyle in a sentence since it has so many
> > moving parts (keys, values, contexts, context patterns).
> 
> ... start off by letting the reader know that zstyle is [complex]

Personally, I find that sentence doesn't actually convey any (objective)
information about what zstyle is or does, so it'd be among the first
things I'd cut.

You are of course welcome to grab a pen or a keyboard and write "Ray's
Introduction to zstyle" (or whatever you might call it) and start it
like that.  If you use a nice markdown editor and put it on github…

> > 
> > 3. Readers (including lurkers) would get a fishing rod rather than a fish.
> > 
> But sometimes what you want is a fish.  That's the perfect analogy tho. 
> Sometimes I
> want a fishing rod, sometimes I want a fish.  When it comes to
> documentation, they
> are very different things.

Perhaps what you have in mind here is the difference between a tutorial
or user manual on the one hand, and a reference manual on the other
hand.

zsh's manual is of the second kind.