Alright, now I understand your remarks a little bit better. I don't think that Nim has a documentation problem in an absolute sense, I think the documentation may seem lacking _for a particular audience_.
As @Araq said in his reply to your list of things that are missing from the tables page, I don't think _the average user_ of the language needs to know about implementation details and have in-depth discussions about performance and why things work in a certain way. Of course, I have my own idea of what _the average user_ is like, which is probably very different from yours. It is, at the end of the day, an audience problem: if you are new to the language, you want a gentle introduction that covers just the basics and lots of examples. If you are into programming language design, you wanna know how things work under the hood and why certain choices were made. If you are an advanced user you just want a quick reference to refresh your memory and carry on. Sadly, I don't think this can be fixed with ONE version of the same document. This problem is typically addressed by multiple documents or specialized articles about a particular aspect, OR we could design a documentation system that provides different "facets" for each topics based on different audiences. I have never seen such a system, and that would still have problems because people wouldn't really know what type of users they are. Bottom line is: you are right in saying that there's something missing from the current docs, but I would argue that the docs are not the right place for it: a specialized blog or a different document would.
