Thank you. Been thinking that since I saw Nim for the first time. The biggest issue with Nim is that the amount of documentation is laughable. Yes. I know all the books & **I have read all the official documentation entirely, several times**. Including all the documentation regarding standard libraries over & over, several times. I have seen changes, improvements, etc. I have been there.
Yet, considering how much Nim offers, the existing documentation, especially the official one, is absolutely ridiculously minuscule. It is an utter joke. It is clearly written by Nim developers, for Nim developers, who are actively developing the compiler already, anyway. Anyone who is not related to the compiler development will struggle with the manual sooner or later, most of the time very soon, though. Even the manual, which offers at least a bit of mercy, is extremely terse, especially in the most important/interesting/noteworthy topics. They are just hinted on, instead of explained, or, god forbid!, presented through examples. (The available examples are too terse, simple & often weirdly annotated, often leaving the option to interpret them very ambiguously.) The BIGGEST reason I cannot always shout out about Nim to everyone I know with good conscience is exactly because of this documentation issue. Whenever a question like "how do I do..." comes up, I can AT MOST show that person like one or two sentences about it, even though this topic would deserve an entire article & more. Most of the time, things are only referenced & not described (as has been mentioned previously), not to mention explained. So, a lot of my experiments in Nim start with reading the tiny bit of documentation available & then I have to dive into the source code anyway & search for Nimble projects, which offer an example made by compiler developers. If Nim would have at least a hundred times (is the minimum amount of documentation it would need to be remotely useful to a wide audience) the amount of higher quality documentation, I guarantee, that the user base of this language would skyrocket, compared to how it's going, now. My claims are based on my personal experience as well as objective data anyone can look up. Look up any significant Nim project & you will see a developer, who is either closely related to the Nim team, a compiler contributer in some way and/or a C OTP since at least two decades, straight. Anyone can do stuff in Nim, but if you really want to accomplish something juicy the Nim way, for example with the FFI, macros, etc. you have to be truly deep into Nim to get the whole picture, even more so the pile of undocumented quirks, "bugs"/"features" & other noteworthy factors. Macros are actually a funny story. There are some examples out there, that's true. But for someone coming from languages, which do not offer anything like that, those examples are not even remotely close to an explanation, which is sufficient for someone without any templating/macro experience in programming. After all these years I still feel like I don't have a full picture about macros. > Maybe instead start with figuring out what is wrong exactly? You say > "documentation is hard". This is a general, non-actionable statement. If you > said "module X has no examples for action Y" this would've been an actionable > statement that can be turned into an issue for anyone to fix. Actually, I think, it's very valid & actionable. If 80% of the documentation is not helpful to a relatively large amount of users, then one should just open the documentation, stop knowing Nim for a second & read it. This sounds tougher, than it is. Additionally, the problem with such "give me a precise example" requests is that, especially in situations of lack of documentation, many cannot point their finger at it. One lacks the knowledge to. How can you know what to improve, if you want to learn, but you cannot learn, because the documentation is bad, so you cannot tell, what exactly is bad? One can say "this is not enough" at some paragraphs, yes, but in general it's hard to point at specific issues & problem definitions. This is even more so emphasised, when you are done reading the documentation for two hours & then **know** it sux. But, if someone comes along & asks you "what exactly sux about it?", then it's again hard to pull out one of the thousand paragraphs you just read out of your head. Especially, since our mind is trained to forget "unimportant" stuff & documentation, which is useless, is unimportant, because it did not help. Having said that, I love Nim & I am happy to help point out the issues in the documentation, with specific examples. I am able to deliver a huge list of issues, very easily. However, do not ask me for a solution to most of them, because most of the time, I don't know if I'm really correct with my conclusions, as the documentation is lacking! Chicken & Egg.
