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.