One of the most frequent complaint about Nim is that it lacks proper documentation. For example, it is mentioned in [2017 community survey](https://nim-lang.org/blog/2017/10/01/community-survey-results-2017.html), [2018 community survey](https://nim-lang.org/blog/2018/10/27/community-survey-results-2018.html) (almost 1/3 of people think better documentation is needed before Nim v1.0 can be released, more than any other single factor), several forum posts and on IRC/Gitter channel.
I think we all can agree that documentation improvements are needed. The aim of this post is to find out what does the **' good documentation'** really mean and how does it look like. To help us with that, please answer the following questions as detailed as possible. For some questions, even if you are experienced in Nim, try to put yourself in the shoes of somebody trying Nim for the first time (or try to remember how was it for you back when you just started). * * * # A. Nim documentation in general [Nim documentation page](https://nim-lang.org/documentation.html) currently contains links to 4 tutorials, 2 books, FAQ, Wiki (last updated in March 2018), standard library documentation, and manual. 1\. Do you think there should be more links to the existing (user-created) resources? If so, which ones? 2\. What resources are needed? Video tutorials, how-to tutorials for some field X (what is X for you?), cookbook (there is/was one, but it seems it is not updated anymore), etc. 3\. Have you used [Rosetta Code](http://rosettacode.org/wiki/Category:Nim) for learning how to do things in Nim? Do you find it useful? 4\. Have you used code practice sites like [Exercism](https://exercism.io/tracks/nim) to learn Nim (or some other language)? Do you think they are useful for learning the language? (Or in Nim case: would they be useful if they had more Nim exercises availbable?) # B. Standard library documentation Some general questions first: 5\. Can you show us the examples of 'good documentation' (GD, later in the text) in other programming languages? 6\. What does the GD consist of? For each module, a general explanation of what it does, code examples of its usage? Long explanations of each function/type/constant? Lots of examples for each function? Links to other modules? Something else? * * * The quality of [standard library documentation](https://nim-lang.org/docs/lib.html) varies from module to module. 7\. What is you major pain point when using Nim documentation? Is it hard to find the module(s) which would be useful to you? Can you understand what a function does based on the description and the example? Are (most of the time) the examples missing or not informative enough? 8\. Is there any Nim module which satisfies your criteria for GD? (It is good as it is, doesn't need any improvements) 9\. Can you show us Nim modules which, in your opinion, have very good documentation? (Only small improvements are needed to make it GD) 10\. Are you willing to help making Nim documentation better? :)
