[TUHS] man-page style

[Theodore Y. Ts'o]

On Sat, Nov 17, 2018 at 10:21:08AM -0800, Kurt H Maier wrote:
> On Sat, Nov 17, 2018 at 11:14:53AM -0700, arnold at skeeve.com wrote:
> >
> > The man page authors / tech writers at Sun were paid to write man
> > pages, and learned / were taught how to do it well. The Linux stuff is
> > done by volunteers.  You're comparing apples and oranges.
>         
> How do we kill this meme?  Linux is open to contribution by volunteers
> but the overwhelming majority of the work done on the OS for *at least*
> the last ten years has been by professionals who are paid to work on
> Linux.

This is true.  Alas, very few of these professionals are technical
writers.  The business model and incentives are different, furthermore
resources such as StackExchange don't exist tend to disincentivize
companies from investing in tech writers --- with notable exceptions
being documentation specific to Red Hat, SuSE, etc.

With commercial products that have competition, prospective customers
can say, "SunOS documentation isn't sufficiently thorough!  I'm
switching to VMS so I can have that wall of three ring binders" :-)

Without that competition, companies are less incentivized to divert
resources to luxuries like documentation --- and the commoditization
of Unix-like systems has reduced the available resources that
companies have available when they are trying to make budgeting
decisions.

(Although I will say, speaking of budgeting decisions, the amount of
human resources I've sent consumed in IBM Fall Plan and Spring Re-Plan
would, if converted from managers and senior engineers to tech
writers, be enough for a truly awesome amount of documentation.  My
condolences to my friends at Red Hat who will soon be getting to
enjoy the wonders of IBM corporate processes.  :-)

	      	     	       	       - Ted