5
halfflat
15d

Best: The Ada 83 Language Reference Manual.

Ada was picked as the teaching language for a while when I was an undergraduate. All the supplied information about the language was at best vague, at worst wildly misleading. But then I came across the LRM in the library, and it had all the answers. All Of Them.

Close runner up: The Annotated C++ Reference Manual.

Back before C++ became too large for any one mortal mind, this reference both contained the 'ground truth' standard _and explanations of what lead to the choices made in that standard_. Just an excellent reference.

Worst: CMake documentation.

The man page was unnavigable, until they tossed it and you had to use the webpage or the idiosyncratically organized help output from the program.

CMake is stupidly complicated already, with bizarre parsing, thousands of odd special case behaviours, and weird interactions between various features and tools. Good documentation might have made that manageable, but no: answering any question requires a measure of clairvoyance, which will inform you that the thing that you need is in fact described off hand halfway down the 4 pages of rambling text in a completely different part of the docs. And then they changed it 2 versions ago.

Comments
  • 1
    ++ for cmake hate, wish there was a good alternative that did the same thing equally well but in a saner way.
  • 0
    @RememberMe meson is probably the best bet. It operates on a similar model of how builds go, and a similar way of describing the steps and dependencies, but there were fewer sleep deprived gerbils contributing to its code base.
Add Comment