[clug] Man pages.

Paul Harvey csirac2 at gmail.com
Mon Jul 27 04:47:00 UTC 2015


On 27 July 2015 at 12:49, Lana Brindley <mail at lanabrindley.com> 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?
>
> L

This is going off-topic, but I've always assumed that efficient
communications must choose an audience.

I used to deal with a lot of RDF/OWL/Ontology data/actor/system
modeling stuff. Consider the concept of
https://en.wikipedia.org/wiki/Reification - it seems simple enough,
but following a conversation takes some getting used to.

Although we can simplify vocabulary, this won't necessarily help in
communicating concepts. I once read an interesting New Scientist
article about a genetics researcher trying to explain her work back
home to a native Urdu speaker. There was no choice but to introduce a
new word, "DNA", before she could even begin to talk about what she
does every day.

Does that excuse crappy technical documentation generally? No. But I
do believe there are efficient technical communications which require
that readers unfamiliar with the subject matter must decide if they
actually need to understand a given document, or face the prospect of
learning a few things as they digest it.

Another example is RFCs (Request for Comments) hosted by the IETF
(Internet Engineering Taskforce). Some are fantastically readable,
especially when the authors want to appeal to a wide audience (Eg. web
developers). But take the RFC describing TLS 1.2 (one of the things
behind the "secure" part of the https:// protocol):

http://www.rfc-base.org/txt/rfc-5246.txt

This is a document written for (and by) people who are *creating* TLS
protocol implementations, of which there must be hardly more than
hundreds of humans doing this at any one time on this planet. Beyond
that, perhaps thousands who need this level of detail. The rest of us
are expected to use more approachable beginner/intermediate texts
which distill this subject matter down to a more widely accessible
form.

And now I see that my own writing gets a slightly lower readability
score than RFC5246. Perhaps I'm the wrong person to be talking about
this...



More information about the linux mailing list