> As for local documentation, suggestions that one must access an > external resource (web site) for documentation pertaining to the > configuration of a piece of critical network infrastructure are > troubling at best. If it's not in a manual page on my local > installation, it doesn't exist.
This. So very this. And not just in this case. Webpage "documentation" is, in my experience, critically broken in at least five ways: (1) There is usually no way to tell whether the documentation you're reading matches the code you have; when there is, there is usually no way to look at the documentation for the version you actually have. (2) It is useless without a connection to the net. (3) It requires a relatively large and bloated program to render readable (even lynx is significantly larger than less, and is a much less pleasant way to read text). (4) Nothing ensures that the documentation remains accessible for at least as long as the software does. (5) They do not fit the existing documentation paradigm ("man foo"). I have seen attempts to fix 1, 2, and 4 by shipping HTML files. Fixing 3 at the same time requires that the files be hand-written with minimal markup, rather than the usual blizzard of mechanically generated markup and insanely long lines that renders the content unreadable with text tools. And even if that's done, that still leaves 5 unfixed, making me wonder what value any software author sees in HTML files over manpages that makes them think it's a tack worth taking. By the way, (1) is a real issue. At work, once, someone wanted me to try to build a go wrapper around some C stuff. I failed, in large part because the (on-the-web) documentation for the reflect package documented a call that simply didn't exist in the code we had. I had no way to tell whether this was simple version skew, bugs, or what, and in any case had no idea what, if anything, could be done about it. /~\ The ASCII Mouse \ / Ribbon Campaign X Against HTML mo...@rodents-montreal.org / \ Email! 7D C8 61 52 5D E7 2D 39 4E F1 31 3E E8 B3 27 4B