> 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.
For what it's worth, I'd generally agree. The docs are mostly good to me, but they're not great either. I actually like that I can reference the manual in page and get pretty much all of the language features there. However, I also find there's odd places where the docs are lacking, or tooling is sorta broken or just not configured right out of the box. Not that I find say Rust's documentation better -- once you get outside of the Rust book the documentation for many crates is terrible. They're often just a list of types and traits, ick. I found giving people Dom's and Araq's book helps quite a bit. They're a bit more guided and experimental bits like concepts are avoided. The Rust book is sorta nice in that way; it's the "conical" introduction and guides people step by step and avoids some trickier areas until much later. Personally I find it way too verbose, but must admit it's effective for a lot of newcomers. > I don't think the doc for getAppFileName is confusing per se, it just doesn't > have sufficient detail on semantics to be sure what the output is going to be > before trying it out. So it leads to surprises. Not a big one, but if there > are a lot of little things like that, you end up with people feeling "death > by 1000 paper cuts". Yes, I've run into lots of little paper cuts. Though, I'm hopeful that along with 2.0 coming out, there will be interest in fixing up many of those. I've already got on PR in for one small pet peeve (thanks @araq!). > However, the impression that I'm getting as someone new to the community is > that, even if people were to step up to the plate, it's not clear the core > team is all that receptive. FWIW, I've found the core team fairly receptive to documentation PR's. Though sometimes it takes a bit of explaining or justifying a change. I'd also say they are particular in what gets added. Starting small helps too. Personally, I think Nim's ecosystem can also grow slowly and steadily and be considered successful. It doesn't need to be a winner-takes-all American VC sort of thing. It's easy to forget that Python took a long time to reach where it is, especially pre machine learning. That said, one of the best parts of Nim 2.0 will be setting a clearer "vision" for Nim. For a long time it seems that Nim was sorta wandering and trying to find it's stride. Getting to more of a focused vision with Nim 2.0 is a great milestone! It looks like there's already plans to begin deprecating experimental features and cleaning up parts of the stdlib. Hoorah!
