man pages - was: wiki vs documentation

[Tom Davies]

Hi :)
+1
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.  


When you install a program the "man" page usually gets copied onto your system as 1 tiny text file amongst many packages.  The normal way to read it is to get to a command-line and type (for example)


man firefox

which gives you a vi text-editor.  They give a lot more detail than the quick-guide cheat-sheets.  Compare that man with the 


firefox --help


The advantage of this type of "manual" is that it is highly specific to the particular version of the program that you have on your machine.  The disadvantage is that it's almost pure geek and needs to remain that way so that other geeks understand it and can easily modify it when they update the package/program.  


There are other ways of reading the "man" pages that attempt to make it a bit easier to read.  It is even possible to find man pages on the internet but then that breaks the number 1 best point about them which is how tightly specific it is for your particular version&build on your machine.  
So i think we can make reference to the "man" pages, just as we can to the quick-guide cheat-sheets, but in the same way i don't think we should be editing them and i think our wiki-pages should be more generic to cover a wider range of versions to avoid getting out-dated so quickly.  It might be good to copy&paste chunks out of some and then re-write or edit to de-geekify but only for our own wiki or official docs.  For example if you were editing the rsync page then it might be wise to have a look at the rsync man page to see if anything significant has changed (probably hasn't) and maybe re-word a few things.  


Regards from 
Tom :)  





________________________________
 From: Elizabeth Krumbach Joseph <lyz at ubuntu.com>
To: Ubuntu Doc <ubuntu-doc at lists.ubuntu.com> 
Sent: Thursday, 19 September 2013, 17:45
Subject: Re: man pages - was: wiki vs documentation
 

On Thu, Sep 19, 2013 at 9:23 AM, Little Girl <littlergirl at gmail.com> wrote:
> Hey there,
>
> Lars Noodén wrote:
>
>> I would like to see the manual pages treated as official
>> documentation. At the very least, they should give a complete
>> summary of the function(s) and options without pointing to third
>> party materials.  Some do, some don't.  All should, because every
>> end user has these pages installed on their machine so it would
>> make sense to use them as the first line of support.  There are
>> systems that take this approach and it works well for them so it
>> could work well for Ubuntu, especially if it is coordinated
>> upstream with Debian.
>
> Where are the man pages kept?

They are all published and searchable here: http://manpages.ubuntu.com/

> Are they on Launchpad?
>
> Are there guidelines for how they should be constructed?
>
> Can any of us edit them? I wouldn't mind going to town on some of
> them. (:

Man pages are typically written by the upstream software project and
then just included in the packages we ship with Ubuntu. As such, any
edits of them should probably be done upstream rather than patching
the Ubuntu packages with our own additions, unless they are
Ubuntu-specific changes that we're looking to document.

-- 
Elizabeth Krumbach Joseph || Lyz || pleia2
http://www.princessleia.com

-- 
ubuntu-doc mailing list
ubuntu-doc at lists.ubuntu.com
https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20130920/13f77482/attachment.html>