man pages - was: wiki vs documentation

[Stephen M. Webb]

On 09/20/2013 05:53 PM, Little Girl wrote:
> Hey there,
> 
> Tom Davies wrote:
>> We should NOT be editing "man" pages.  They are primarily written
>> by devs for devs and sometimes just about understandable for tier3,
>> maybe tier2, IT Support.  They are NOT for general consumption and
>> definitely not for noobs!  You probably understand most of them as
>> you are all quite advanced users but even you will struggle with
>> quite a bit of it.  Well, i do.  
> 
> Most of us do, I think. Maybe a compromise can be made by the
> documentation team reaching out to upstream and letting it be known
> that there are some of us who would be happy to look over any man
> page and add a user-friendly explanation and/or examples section. I
> volunteer to be on the list of people upstream can contact. Any
> others? (:

I'll give you a bit of insight from an "upstream":  few upstream developers can put a sentence down on paper and are
completely blind to the existence of documentation, man pages included.  It just does not exist in that rarefied
atmosphere.  Much of the time man pages are actually added to a package by the packagers, who are very often completely
different people than the upstream developers.  It's incredibly unlikely an upstream would ask someone to look over
something that they're probably unaware of and almost certainly wouldn't consider important.

You generally don't have to join an upstream project to contribute docs or manpages.  It's usually enough to file a bug
against the project with a correction attached.  It's the writing (content) that's the difficult part, not the format or
mechanic of inclusion.

-- 
Stephen M. Webb  <stephen.webb at canonical.com>