Ask HN: Long standing bugs as part of documentation

You know the situation. You've inherited an old code base recently and trying to install all the legacy stuff, you run into some inconsistencies. The documentation clearly explains how to set things up. You do this and do that and Bob's your uncle. You follow the steps and everything seems to work... to a point. There's some strange behavior that makes you wonder if you skipped a step. Nothing major, just some small annoyance that you could hack around, but the documentation does not mention it, so you feel uneasy about it. To give some concrete examples, a library failing to connect to the URL you've specified in the config file, even though the documentation clearly says it should be able to; or a daemon properly producing log files, but somehow owned by a user other than the one you specified to switch to, as directed by the documentation.

Thus begins some potentially long rabbit hole, which ultimately ends with you emerging at the (still open and very popular) ten year old tickets reporting the (mis)behavior. In the first case for example, it's revealed that the library can't connect to HTTPS. And now that you pay closer attention to the documentation, you realize that it, too, seems to pretend it's an HTTP world! In the second case, the ticket reports that for everything else, the functionality works as expected, but due to some obscure design choice, the logs are produced as root. In both situations, the problem is well known. The longevity of the tickets implies that a solution is not going to be simple. Yet, the documentation acts oblivious.

I think that well known long standing issues should be included in the documentation. I understand that no one is proud to advertise their shortcomings, but a ten year old bug is not a bug anymore, it's a feature, albeit a surprising or inconvenient one. Keeping silent about it is tacitly misleading your users.