== Solaris gives us a lesson in how not to write documentation

Here are links to the manpages for _reboot_ in [[Solaris 8
http://docs.oracle.com/cd/E19455-01/806-0625/6j9vfilu2/index.html]],
[[Solaris 9
http://docs.oracle.com/cd/E19683-01/816-0211/6m6nc674n/index.html]], and
[[Solaris 10
http://docs.oracle.com/cd/E26505_01/html/816-5166/reboot-1m.html]] (or
the more readable [[Illumos version http://illumos.org/man/1m/reboot]],
which is probably closer to the Solaris 11 version). They are all,
well, manual-pagey, and thus most system administrators have well
honed skills in how to read them. If you read any of these, it
probably looks basically harmless. If you read them in succession
you'll probably wind up feeling that they're all basically the same,
although Solaris 10 has grown some new x86-related stuff.

This is an illusion and a terrible mistake, because at the very bottom
of the Solaris 9, Solaris 10, and Illumos versions you will find the
following new section (presented in its entirety):

> ===== NOTES
>
> The _reboot_ utility does not execute the scripts in _/etc/rc*num*.d_ or
> execute shutdown actions in inittab(4). To ensure a complete shutdown
> of system services, use shutdown(1M) or init(1M) to reboot a Solaris
> system.

Let me translate this for you: ~~{{ST:strike:since Solaris 9,}} _reboot_
shoots your system in the head instead of doing an orderly shutdown~~.
Despite the wording earlier in the manpage that 'the _reboot_ utility
performs a _sync(1M)_ operation on the disks, and then a multi-user
reboot is initiated. See _init(1M)_ for details', SMF (or the System V
init system in Solaris 9) is not involved in things at all (and thus
no multi-user reboot happens). Reboot instead simply _SIGTERM_s all
processes. That stuff I quoted from the DESCRIPTION section is now a
flat out lie.

This is a drastic change in _reboot_'s behavior. It is at odds with
{{ST:strike:_reboot_'s behavior in Solaris 8 (as far as I know),}}
the [[traditional System V init behavior ../unix/InitHistoricalRoles]],
and _reboot_'s behavior on other systems (including but not limited
to Linux). Sun decided to bury this drastic behavior change in a
casual little note at the bottom of the manpage, so far down that
almost no one reads that far (partly because it is after all of the
really boring boilerplate).

This is truly an epic example of how not to write documentation.
Vital changes go at the *start* of your manpages, not the very end,
and they and their effects should be very clearly described instead
of hidden behind what is basically obfuscation.

(The right way to do it would have been a complete rewrite of the
DESCRIPTION section and perhaps an update to the SYNOPSIS as well.)

By the way, this phrasing for the NOTES section is especially
dangerous in Solaris 10 and onwards where SMF services normally
handle shutdown actions, not _/etc/rc*num*.d_ scripts (or _inittab_
actions). In anything using SMF it's possible to read this section
but still not realize what _reboot_ really does because it doesn't
explicitly say that SMF is bypassed too.

~~Update~~: As pointed out in comments by [[Ade
http://www.big-bubbles.fluff.org/]], this appears to be historical
Solaris behavior (contrary to what I thought). However, it is not
the (documented) behavior of other System V R4 systems such as [[SGI
Irix
http://techpubs.sgi.com/library/tpl/cgi-bin/getdoc.cgi?coll=0650&db=man&fname=/usr/share/catman/a_man/cat1/reboot.z&srch=reboot]]
and it is very likely to surprise people coming from other Unixes.