Date: Wed, 6 Aug 2014 17:59:07 -0400 From: Paul Kraus <paul@kraus-haus.org> To: FreeBSD Questions !!!! <freebsd-questions@freebsd.org> Cc: Polytropon <freebsd@edvax.de> Subject: Documentation WAS: pkg question .... Message-ID: <10FF0A4F-F96E-4A68-BA25-56B57AFD4B2E@kraus-haus.org> In-Reply-To: <20140805225107.ccf9944a.freebsd@edvax.de> References: <53E0D2B7.9060402@hiwaay.net> <20140805131910.GA72939@slackbox.erewhon.home> <53E0E281.9030306@hiwaay.net> <20140805225107.ccf9944a.freebsd@edvax.de>
next in thread | previous in thread | raw e-mail | index | archive | help
On Aug 5, 2014, at 16:51, Polytropon <freebsd@edvax.de> wrote: > Please understand that "modern" software does not come with > manpages anymore. Thank you for putting =93modern=94 in quotes. > Documentation, _if_ it actually exists, is > scattered across the web. And we know how much we can trust what we find =93on the web=94. > 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 =93modern=94 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, =85) where man pages were all = available but NOT part of the core installation, they were included in = the =93Developer=94 tier :-) So I am used to being able to type =93man = <almost anything>=94 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 =93read the = source code=94, 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=94. 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> =97help. 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 =85) There have been = entire *books* written on the use of sed, awk, and even sh (see the = O=92Reilly 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. ;-)=20 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@kraus-haus.org
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?10FF0A4F-F96E-4A68-BA25-56B57AFD4B2E>