[clug] Man pages.

Scott Ferguson scott.ferguson.clug at gmail.com
Mon Jul 27 14:04:55 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?
> 
> L
> 
My apologies Lana, after consideration my use of "obvious" was,
ironically, wrong. It's only obvious to some writers of technical
communications.

Like any writing you write to the audience. One of the ways to make the
information easier to digest is to avoid inadvertently insulting them
e.g. like I did saying that the difference between readability for a
broad baseline of comprehension and a specialised on, is obvious.
That means treading the thin line between presuming they know the jargon
of a field and risking insulting them by explaining to them what they
already understand. The longer they (reader, listener) have to wait
(listen, read) to get the core information, the more likely they'll
wander away out of boredom, or bolt it down from hunger when it arrives
without enjoying the flavour and presentation (context and conditions).

Restaurant metaphors... snack time.

At one time I wrote Windows help documentation (a format, not 'for'
Windows). A good, experienced writer can produce about two high quality
100 word pages a day. It's hard. Yet it seems easy until it's subjected
to reader testing. I used to produce two pages on a occasional good day.

At best readability tests ensure you avoid common grammar mistake and
help keep documents free of unnecessarily long words out of
documentation. They use a simple bad grammar rule set and various
logarithms based around number and length of words to determine relative
levels comparative to basic education levels. Throw in some acronyms,
long paths, jargon (or gibberish), or URLs and the algorithms fail to
give useful results. If you're interested the algorithms are documented
in one of the links I posted earlier.

You probably know 'all' this[*1], but I write to a larger audience as
well (and also because I like to write).


Kind regards


[*1] I've only just read your bio. You are a professional writer, with
an academic background. It's very unlikely I haven't read your work
before - I don't tend to pay much attention to names unless I meet
people (or the writers are dead).
I write, and talk a lot, but am definitely not a professional writer -
and my academic background is not in writing. Any criticisms or
suggestions would be greatly appreciated.



More information about the linux mailing list