1. Sure, but only if the links are not going to become outdated or irrelevant with time. It looks bad to have external links if they simply result in obsolescence. **If (and only if!) external resources are up-to-date ane directly relevant, should they be included.** 2. We need both video tutorials (I learn by watching/hearing, not reading, and I'm sure there are others) and better top-level examples for each module in the stdlib. Often, I can tell what a given type or procedure does, but it's unclear why the entire module is part of the stdlib or whether it is maintained. Related: When I first learned Nim, I saw so many different styles in the wild, I wasn't sure which one was current. Are reference types called `PType` or `TypeRef`? Are `enum` s supposed to be `pure` or not? Do we prefix them? Do I return a value by assigning to `result` or making an expression the last line? **Since Nim is so diverse and flexible, we need some sort of expansion upon the Style Guide to reflect these changes. Also, the Style Guide isn 't well advertised to beginners, IMO.** It took me a while to think to look for one. 3. I used Rosetta only once, but I like knowing it's there LOL. 4. No, I never use code school kinds of things. I just hit the ground running by solving Project Euler problems or implementing a little toy project. I did use tut1 and tut2, although I often found them too brief compared to _Learn You a Haskell For Great Good_ or _The Rust Book_. 5. The [Rust Docs](https://doc.rust-lang.org/std/) are great if you ask me. The landing page explains why each module is important and the goals of the stdlib as a whole. 6. Good Docs include examples for anything _not obvious_. The goal is to communicate information to all users of the library. Many times the documentation in Nim is more than sufficient for the core devs but intimidating for beginners. It 'd be nice to have a smoother introduction to each module, at least one example that shows how the module can help solve a practical problem, and examples on any complicated procedures. We need to collectively remember that our audience is all Nim users, not just the "pros". Languages like Python are notable for embracing beginners and welcoming them with compelling, relevant documentation that _makes people stay with the language_. Docs should be users ' friends. Nim has the technical basis to be useful in so many domains, but few people are willing, or even able, to acquire knowledge by brute force. **I shouldn 't feel so accomplished simply because I can glean useful tidbits from the docs. The docs should empower our users.** The Nim community can't gain momentum if we don't advertise what we have to offer. We don't have to be, or want to be (!) C++, and our goal may well be to be better, not popular, but at the end of the day, we only get back what we give, and our documentation is inadequate in the face of better options. Nim's documentation is one of the single largest roadblocks for widespread adoption. 7. The pain point is that the module docs often don't include some overarching summary that discusses each procedure's purpose. Now, not every simple constructor or stringify operator needs an explanation. I appreciate how the [options](https://nim-lang.org/docs/options.html) module has two examples at the beginning that make it clear what problem the module intends to solve, and, most importantly, **how those solutions can be applied to your own project**. Even then, the description is rather short. In this case, there should be discussion of why options are indeed superior to nillability and how ` Option[T]` is an _algebraic data type_ inspired by functional techniques that can help prevent bugs and document intent. Without that background, most people will look at the module and say, "Cool, okay, whatever" and just use `nil`. In order to build a strong ecosystem around Nim, the docs need to be good teachers that support eager learners. The current docs often fail to document intent, and hence end up being overlooked. **The re-entrant locks module is a perfect example of insufficient docs**. [Have a look](https://nim-lang.org/docs/rlocks.html). It has a sentence for every procedure, but... No background. No examples. No explanation of purpose, intent, or applicability. No new user will use that module. Guaranteed. 8. No, but I'm optimistic anyway. 9. I don't know, that's rather subjective. @Araq is right that there is no universal endpoint where okay docs become sufficient docs. It's an invisible scale. But, I can say that most modules need attention. `options` is better than most. `asyncdispatch` has a good introduction. 10. I'd love to help. After all, I just wrote about how action is needed. Currently, I'm towards the end of some difficult classes, and that takes most of my free time. My few PRs have languished. I hope to change this in the future, as I want to help remedy this situation. When my life allows, I'd be happy to add examples, write summaries, and discuss improvements with the community. I need to add something though. See below.
* * * I have an idea, and I hope its a good one. We should have a contribution coordination system for documentation! Rust has a GitHub bot that assigns features and bugfixes to specific contributors. **We could launch a website where members could register to contribute and choose a frequency /level of contribution.** We would keep a database of modules and a "priority level" for each (some are more urgent than others). Then, the system would assign a contributor to a module that needs to be documented. In this manner, contributors would have a way to start. There could also be a forum for each module where community members can discuss ideas. I would find this motivating. Often, I want to help but don't know where to start. This system could allow the community to collectively coordinate documentation improvements, and could provoke a real facelift effort backed by many. Any ideas? Let me know what you think :) Cheers
