Documentation WAS: pkg question ....

[Paul Kraus]

On Aug 5, 2014, at 16:51, Polytropon <freebsd at edvax.de> wrote:

> Please understand that "modern" software does not come with
> manpages anymore.

Thank you for putting “modern” in quotes.

> Documentation, _if_ it actually exists, is
> scattered across the web.

And we know how much we can trust what we find “on the web”.

> You'll find it in discussion forums,
> blogs, user home pages, and wikis. Sometimes, there's something
> in /usr/local/share, but don't bet your money on it... :-)

And that was (and is) one the reasons I have chosen FreeBSD for my production systems. And I mean that is a very positive way. The documentation, all of it, not just the man pages, for FreeBSD is very much supper to what one can find for many other “modern” operating systems <cough, cough, Linux>.

I originally cut my teeth on SunOS / Solaris (not counting the time I spent with C/PM, Basic, Cromix, AmigaDOS, …) where man pages were all available but NOT part of the core installation, they were included in the “Developer” tier :-) So I am used to being able to type “man <almost anything>” and getting useful information (often way too much, try `man sh` sometime). So I am spoiled in that regard.

On concrete example of how the FreeBSD documentation beats the pants off of Linux (I forget the distro right now). I had a server running FreeBSD with VirtualBox for virtualization. I had both FreeBSD and Linux VMs. There was a problem where the boot block on the VM was damaged. By looking in the FreeBSD Handbook I was able to find the boot process documented, this enabled me to reconstruct the boot block fairly painlessly. I had the same issue happen with a Linux and VM and finding the details of *how* the system boots was like pulling teeth. One document just referred to another and round and round. The documentation for GRUB, especially GRUB2, is particularly cryptic *if* something is going *wrong*. Of course the short answer is always to just “read the source code”, which, as anyone who is not intimately familiar with that particular piece of code can tell you, is almost useless.

In my opinion, documentation is one of the signs of professional, mature software. Thank you to all the varied FreeBSD people who have contributed to the stores of official (or at least semi-official) documentation available.

> No, seriously: Most desktop environments don't have manpages.
> Few programs have, because nobody reads them. Still there are
> some exceptions, like "man opera", "man openoffice", "man xmms"
> or "man gmplayer". On the other hand, try "man firefox", "man kde"
> or "man grip”.

There can be good reasons to *not* include a FULL man page for a graphical tool, but at the very least the command line options and arguments ought to be documented. Even if the man page is not more than a glorified version of <command> —help. But putting the FULL documentation in a man page is really silly (see my earlier reference to the man page for sh; or bash, or see or awk or …) There have been entire *books* written on the use of sed, awk, and even sh (see the O’Reilly Nutshell books for great examples), putting *all* you can do with sed in a man page is overkill.

> On one of my older systems where I have XFCE 3 installed, when
> I type "man xfce", do you know what happens? A manpage appears!
> You can see: Sometimes, someone made a decision not to maintain
> manpages anymore and instead concentrate on software features,
> look & feal, following the most recent Linux development and
> just coding along. This is a _valid_ decision, even though a
> minority of 0.01% of the users might not appreciate it. ;-) 

I understand that developers want to develop and not write manuals. And since most of this is being done for fun, they concentrate on the fun parts. I actually think that for many man pages the number of people who use that function (program, configuration file, etc.) that would like a good man page is much higher than your 0.01% number. I am thinking mainly of system admin functions that most end users never even think about, but let the automated install scripts handle for them.

--
Paul Kraus
paul at kraus-haus.org