[clug] Man pages.
Bryan Kilgallin
bryan at netspeed.com.au
Tue Jul 28 01:25:06 UTC 2015
Hi Eyal:
> "readability" is a vague term that means nothing without a clear
> definition.
Short sentences and short words help!
> Different technical fields have different standards of expression, so
> much so that you might as well treat them as different languages.
I was in a health care consumers' association. So I reviewed a nursing
document. Which was written in nursing-jargon!
> However, when the context (mostly the audience) is known it is
> possible to assess readability.
Rather than being known--it's often assumed. The writer assumes that the
reader is like them. Which is often untrue.
> An example: A computer program has the compiler as the audience.
The documentation might consider the user.
> Yet, some can argue that a program is less readable than it should be.
The extreme case is a write-only language!
https://en.wikipedia.org/wiki/Write-only_language
> Now we consider the other (subject matter aware) programmer as the
> audience.
Experts in two disciplines might be considered. One of those is
programming. The other is the business domain.
--
www.netspeed.com.au/bryan/
More information about the linux
mailing list