[clug] Man pages.

Scott Ferguson scott.ferguson.clug at gmail.com
Mon Jul 27 07:01:13 UTC 2015

On 27/07/15 14:47, Paul Harvey wrote:
> 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...

Agreed, you've echoed much of what I've tried poorly to express in my
reply to Lana. Your first sentence is excellent.

You'll score poorly because you're using acronyms and a URL. It suits
the audience (as per your early point).


Kind regards

More information about the linux mailing list