Web "documentation" [was Re: Removing PF]

[Mouse <mouse%Rodents-Montreal.ORG@localhost>]

> 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		mouse%rodents-montreal.org@localhost
/ \ Email!	     7D C8 61 52 5D E7 2D 39  4E F1 31 3E E8 B3 27 4B