[clug] Man pages.

Bob Edwards Robert.Edwards at anu.edu.au
Mon Jul 27 04:59:57 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...
>

I agree. Man pages were originally written _by_ System Admins and
Programmers _for_ System Admins and Programmers. They are a useful
reminder of how to invoke a function call etc., not intended to be a
beginners guide to programming or system administration.

Keep the man pages short and succinct and go to the textbook for the
introductory material.

Having said that, one of my great peeves with man pages is those that
omit an "Example" section. Those that have them are _great_ - those
that don't are generally a lot harder for an old codger like me to grok.

cheers,

Bob Edwards.



More information about the linux mailing list