[clug] Man pages.

Eyal Lebedinsky eyal at eyal.emu.id.au
Mon Jul 27 05:38:02 UTC 2015


On 27/07/15 12:49, Lana Brindley wrote:
> On 27/07/15 11:40, Scott Ferguson wrote:
>
> <snip>
>>
>> If he was referring to the content of man pages. Determining the
>> readability of man pages (or any technical documentation) is not as
>> simple as assessing it by readability tests designed for non-technical
>> writing - for obvious reasons.
>
> I know you say it's obvious, but I don't understand. Why should tech
> comms be held to a different level of readability to non-tech  comms?
> Can you expand?

You did not ask me but since the door was open...

"readability" is a vague term that means nothing without a clear definition.
It changes vastly with context. Different technical fields have  different
standards of expression, so much so that you might as well treat them as
different languages.

However, when the context (mostly the audience) is known it is possible to
assess readability.

An example: A computer program has the compiler as the audience. Yet, some
can argue that a program is less readable than it should be. Now we consider
the other (subject matter aware) programmer as the audience. Satisfying both
is usually impossible, which is why comments(*) were invented.

But you can explain the program precisely using a formal logic, which is
often more unreadable than any of the above.

This was me making a point using an extreme example. most audience fall
somewhere between a compiler and a human.

> L
>

(*) some programmers reading this may be unfamiliar with the term...

cheers

-- 
Eyal Lebedinsky (eyal at eyal.emu.id.au)



More information about the linux mailing list