I suspect the thread I saw got locked because people might not want to discuss the docs. Clearly a lot of work has been put into them, and I do think they're pretty broad. The documentation feels sufficient in most areas for grey beards coming from C like myself; I picked up the language less than 2 months ago, and am quite enamored with it.
Still, I do believe the docs are objectively "good", I do not believe they are sufficient for the level adoption that I think Nim should have, even within the stated target niche (specifically, more seasoned programmers). Given I want to see Nim take over the world, I thought it was worth sharing my perspective, which I personally feel is objective, and not cluttered with a long history with the language. For me, occasionally the docs aren't going to be sufficient no matter what, but I'll ask around, and I'll go read the code. But if most people are going to invest in a new language, even the top tier engineers will want to minimize the amount of times they have to rely on those options. If it seems like it'd be a frequent occasion, then most of them will self-select out quickly. I'd say I had to ask around and go look at the implementation a bit more than I wanted, but it was fine for me. Still, I have a much higher tolerance for this than most people, especially since I think Nim hits absolutely everything I want in a language. So I look at it from the perspective of how well is the documentation serving other people new to the language. There, I have two sets of data points, one from the chat room, and one from co-workers. I've sat in the chatroom for the last month or so, and seen plenty of people already who seem likely to have given up quickly on Nim because it's not always clear enough how to do fairly simple things for expert developers, without digging into implementations. That hasn't just been programming beginners coming from Python; it's included, just as a single example, multiple people who understand generics and interfaces in other languages, but don't find the docs on concepts sufficient. First, people coming at from languages like Go who are expecting more of an 'interface replacement' don't understand that they're not concrete types. They want to declare arrays of their concepts and then mix adding in ints, objects and strings to some seq[] and don't understand why they can't have a seq of their concept. Second, people who have a more deep understanding of parametric polymorphism, might not have that issue, but have definitely seen people not understand enough when you need multiple variables defined on the concept line, and why you'd want to have them be modified there (e.g. with var or ref). The documentation that does exist gives plenty of examples of declaring concepts, but, to my recollection, NO examples of actually instantiating and using them in the ways people are likely to want to use them. I've seen similar problems with, for example, the OpenSSL integration. Having written a book on OpenSSL myself, I know that library sucks big time, and their documentation, while extensive, is still garbage. But beyond the actual wrapping of a socket, the nim-level documentation of the API isn't really there, and it probably should be, because a bunch of people come in wanting to use cryptography in some way; I just got done fielding one issue in the chat room, where the person was using an INCREDIBLY crappy 3rd party library to do basic AES encryption that should be available any time -d:ssl is on. Unfortunately, these are the kinds of things that will cause even GOOD experienced developers to bounce. Otherwise, I do generally agree that the standard library docs in particular are decent enough, though it'd occasionally would be great to have more depth. For instance, the first time I had to use os.getAppFileName(), the fact that the documentation was right under os.getAppDir() let me to assume that os.getAppFileName() would be _just_ the file name, not the full path (i.e., that I would need to do joinPath() on the two. It wasn't a lot of friction to find out I was wrong and fix it, but those are pretty basic semantics that _should_ be in the docs that aren't. Enough little paper cuts like that will drive away many people from the target audience. Still, in general, I do agree that the documentation (while perhaps being adequate for people who are excited to learn the language) is not adequate for most people coming to the language. I've got several people at work who, on paper should like the language, and are smart, senior engineers, who love the concepts. But they have been turned off by the docs, and are not willing to put in the effort to switch from Go or what have you. All in all, two months in, Nim's my favorite language of all time (and over the last 25 years I've taught both programming languages and compilers plenty of times). I do feel like it _should_ be a lot more popular than it is. You can attribute some of that to the fact that a lot of the languages to take off in the past decade have had big money put behind it from big tech companies, and that's a limiting factor. But I don't think that would be an issue; I think far more people would be reaching for Nim than, say, Rust if the docs were more mature, and if the tooling ecosystem were more mature and better documented. For instance, one member of my team tried to get the VSCode integration working, installed one of the major lldb integrations, and yet for whatever reason, none of his set breakpoints would ever fire. He couldn't find any FAQ or README to help quickly, and that was the final straw, he went back to Go. Maybe he was just doing something wrong, but he knows how to use a debugger w/ VSCode (whereas I'm just a unix grey beard using emacs as my IDE). Anyway, getting new people in the ecosystem might not be the largest priority right now, so I'm not saying this is a 'problem' that definitely needs to be fixed. The docs are certainly good enough for _me_ and, I'm not going to bounce out to something else easily. But I do think, even as comprehensive as they are, that's not comprehensive enough for MOST people to make the jump to a language, especially with a relatively small ecosystem when compared to the languages they already use. If the ecosystem were bigger, maybe the docs would be sufficient. But I believe the ecosystem can't grow fast enough for that, unless the docs are even better than they already are, by a lot.
