[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!

> 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.


More information about the linux mailing list