Re: Tagged parameters

[Clinton Bunch <cdb_zsh@zentaur.org>]

On 8/15/2023 17:41, Grant Taylor wrote:
> On 8/15/23 1:10 PM, Ray Andrews wrote:
>> The problem of manuals being written by people who are already 
>> experts is always hard to avoid.
>
> Who would you suggest write about ${TOPIC} if not someone that has 
> already learned about ${TOPIC} and ostensibly has some level of 
> mastery / expertise thereof?
>
>> Manuals must serve the person who is not already an expert and that's 
>> difficult because the minds are different.
>
> I don't agree.
>
> Documentation, of any sort, is better than no documentation.
>
> N.B. I don't consider source code to be documentation that is 
> accessible by most people.
>
> Yes, there is some documentation that tends to qualify as more 
> reference material and other documentation that qualifies as more 
> teaching material.  Traditional manual pages are often an example of 
> the former. While Ho-To guides on The Linux Documentation Project tend 
> to be examples of the latter.
>
> I believe there are places for both types of documentation. What's 
> more is that neither type of documentation precludes the other from 
> existing.
>
> I would much rather have something terse, dense, and quick from a 
> programmer that doesn't have time to word smith than not have even that.
>
> Others who don't feel comfortable can take the snippet from the 
> programmer and turn it into more friendly if not training friendly 
> documentation.
>
I always thought that was what technical writers were for.


Of course, we could always hand it to ChatGPT to write the Zsh manual :)