Stuff I have managed to learn without consciously being aware of having done so:

  1. If you’re going to “mirror” content at various locations — please make sure the mirrors are current, complete and accessible.  Failure to ensure ALL THREE conditions makes the “mirror” worse than useless, but actively ensures that the various “mirrors” will basically “fight” one another.
  2. IF something is not blindingly, intuitively obvious: document it — in as excruciatingly-detailed a manner as possible.   If it IS blindingly obvious: document it meticulously, anyway.  Don’t assume that everybody makes the same “intuitive” leaps/brings exactly the same “background” to it, as you do.
  3. “Change-logs” are infinitely less important than the rest of the documentation.  It does me absolutely no good to know about some obscure changes between versions 2.66614 and 2.66615-pre-alpha if I have no idea how to even DOWNLOAD AND INSTALL the useless piece of shit!

Seriously, folks: DOCUMENTATION IS (nearly) as important as the device/program itself.

Failure to document is the equivalent of a featureless black cube, with a series of (unlabeled) knobs and switches.

INADEQUATE documentation is like “labeling” the controls in esparanto or Klingon or something. — just so you can then bitch about how people should RTFD (“read the fucking dictionary!”).

Yeah… this point, I really want to throat-punch somebody. 😦


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s