[clug] Man pages.

[Scott Ferguson]

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
> 

Because they're aimed at different audiences, and have different format
constraints. Hang in there, I'll try and be as succinct as possible
within my time and mental limitations. Disclaimer - this is *very* much IMO.

Readability involves several factors. The main ones are how clear it is
(unambiguous), how easy it is to understand.

To generalise - those readability tests determine how easy it is to
understand based on the size of words.

Which is a good indicator until applied to writing that uses acronyms,
program names, products, and processes. The use of those increase in
technical areas. Jargon is good - for those initiated in their meaning.
Painful for who aren't. And difficult for those who need to explain them
as they present the problem of needing to make them clearly understood
whilst keeping the writing total within a digestible limit.

Those readability tests are very useful when writing for a general
audience - because the scores are meaningful. Up to about Year 12 of
formal education everyone has close to the same understanding of words -
and understand close to the same amount of words (or relatively at least).

When education becomes specialized, whether formally or informally those
indexes used by readability tools are less reliable. e.g  "logical
schema" means different things to an IT graduate than someone who has
studied philosophy, and may mean nothing to a medical graduate.

If you are not a student of cricket the silly maiden needs expansion. If
you know little of fashion haute couture could be mistake for food.
(Wikipedia will tell you it mean "high fashion" - a trade seamstress or
tailor will tell you it means "cut and drape")

Hence my claim that those tools are not of much use when writing
technical information.

"Clear writing" is more important. That's not to say it's not important
for non-technical writing, only that we are more adept at guessing the
meaning.

e.g. Though Bob misunderstood Keith's meaning, at least two others
didn't (probably not a good example as Keith left out pertinent
information, and Bob may have extrapolated from something else Keith had
written previously)

A better example: I met the ambassador riding his horse. He was snorting
and steaming, so I gave him a lump of sugar.

Those readability tests won't catch that, but most of us will, and the
grammatical error is not such that we would all damn the author (I hope).

Make the same mistake with a chemistry procedure - or a man file for
raid and we will damn the author.

A technical guide needs to be unambiguous. It also needs to be as short
as necessary for it's intended use. i.e. a 'man' page longer than is
necessary for a command with many options should be expanded in an
'info'. Beyond that is should be in a howto. Beyond that - a book.

e.g. samba has a bunch of options, if you use it regularly you'll want
to quickly find the ones you need - not go through wreathes of
explanations for n00bs.

That's where hypertext comes into it's own - a writer can keep things to
succinct chunks, and a reader can get the expansions when, and as they
need them without losing their place.

I use readability tools, I also try and employ critical thought, and I
rely strongly on proofreaders. I'm not a professional writer. I've used
none of those things when writing this, and it only "seemed" OK after a
quick re-read - my apologies in advance for all the very likely errors.



Kind regards