man pages - was: wiki vs documentation

[Little Girl]

Hey there,

Stephen M. Webb wrote:
> Little Girl wrote:
> > 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.

Then perhaps we should extend our offer to the packagers. (:

> 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.

Yep. Elizabeth wrote a great message about that here:

https://lists.ubuntu.com/archives/ubuntu-doc/2013-September/017860.html

> It's the writing (content) that's the difficult part, not the
> format or mechanic of inclusion.

I'd be happy to try my hand at some of that writing. I'll see what I
can do. (:

-- 
Little Girl

There is no spoon.