Re: Tagged parameters

[Grant Taylor <gtaylor@xxxxxxxxxxxxxxxxxx>]

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.