Re: [groff] man-page fixes

[Damian McGuckin]

On Fri, 23 Nov 2018, Larry Kollar wrote:

> Nowadays, minimalism is all the rage. Omit needless words, as
> Professor Strunk wrote in 1918.

A (shortened?? 26-page) version of which is at

        
https://faculty.washington.edu/heagerty/Courses/b572/public/StrunkWhite.pdf

The 4th and latest edition is 109 pages in total. The original was done
as part of Project Gutenberg.

        http://www.gutenberg.org/files/37134/37134-h/37134-h.htm

although I prefer the version 'extended' by E.B. White.

Not sure that 'minimalism' is the same as 'omit needless words' but then, 
I do not write user manuals for a living like Larry.

My manpages are written to explain that upon which I have been working. 
The big problem is being able to step back from work with which one is 
highly familiar and being able to explain it to a newcomer. So, content, 
clarity and consistency (of style) is crucial! Strunk has some nice advice 
on style in his Chapter V.

In what seems like a gazillion years ago, both DEC and IBM wrote manuals 
using a subset of English to make their manuals easy to read for those for 
whom English was not a native language. I would love to be able to find 
the rules which governed the writing of such manuals.

Regards - Damian

P.S. Strunk has his detractors (although I am not one of them)

        http://www.lel.ed.ac.uk/~gpullum/LandOfTheFree.pdf

Pacific Engineering Systems International, 277-279 Broadway, Glebe NSW 2037
Ph:+61-2-8571-0847 .. Fx:+61-2-9692-9623 | unsolicited email not wanted here
Views & opinions here are mine and not those of any past or present employer