Thought this deserves it's own thread. The notion that current Nim docs are not the "best in the biz" is a common one and the issue is raised regularly (I don't think there's ever no room for improving the docs actually). I'd be happy to support this point of view with some data but unfortunately, the Nim Community Survey is not very useful for this. There's no way to directly tell what the users want as there was no direct comparisons of tensions points they are having with Nim. It only shows that docs are less important than fixing bugs (you don't need a survey for this).
The main deficiency I see is the neglect on the prescription side of the docs, even where the description side is ok. The curse of knowledge is too evident throughout the ecosystem. I sincerely hope this is unintentional and is a result of paying attention to hard technical problems first, and not some form of arrogance or subconscious attempt to put filters on the level of the expertise in the community.
Speaking of which. To lift the curse of knowledge at least partially and to simply have more helping hands you need to engage more community members of different technical levels in the docs improvement effort. Oh, but is there one? I don't know of any. There should be a coordinated effort with a roadmap, a standard and some form of a protocol such as: "one big feature with a module requires 3 code examples of different levels of complexity, a list of real-word usage cases, 1 separate tutorial in a more verbose language." Or something different, this is just from the top of my head.
The upcoming channels is a good example, as there's an accompanying blog post already written. This should be the standard way of releasing new features, even smaller ones. Iterable just landed but itertools is just a draft and there's no show-case blogpost in sight. Yeah, it's (unfortunately) a small feature, but why not write an accordingly small post?
Implementing an RFC? Engage some community volunteers (or at least throw help-wanted signs) who's not directly working on the code to write/improve this particular piece of docs or write a tutorial. I believe you'll find a few people who'll be happy to help if they feel they are guided and the amount of work is not overbearing. So, "attach" people and assemble working groups.
Herding cats requires more leg-work, so assign more and nag people more so they aren't wandering on their own all the time.
I need some guidance
Have you finally read my book carefully?
This is not exactly the topic of the thread, but it's important too. The official book would be great. The Rust book, for example, was just brilliant at some point, but it evolves constantly and I don't know how good it is currently. For now we have Computer Programming with the Nim Programming Language by @Stefan_Salewski as a free option and Nim In Action by @dom96 for not a lot of $.
nim-by-example is a separate class of "get a glance and a first taste" tutorials, very important obviously. I see it's still maintained which is very good, but learn Nim in Y minutes is almost a year old, I think it should be in the scope too.
@juancarlospaco mentioned a Nim wiki on GH which has a few very good pages but I have my doubts as to how convenient GH wikis are in general to maintain and control for information staleness.
There should be a coordinated effort with a roadmap, a standard and some form of a protocol
maybe, but in practice, actual PR's tend to be more effective than simply talking about how we need coordinated effort, roadmap, protocol. eg PRs like these: https://github.com/nim-lang/Nim/pulls?q=is%3Apr+sort%3Aupdated-desc+author%3Akonsumlamm+is%3Amerged
Now that runnableExamples work inside templates (https://github.com/nim-lang/Nim/pull/18082), an easy way to contribute is converting (and improving) code-block's to runnableExamples throughout stdlib.
not some form of arrogance
Unfortunately there is some. It was there already in 2015, when I tried hard to proofread doms book, and some of my serious comments have been ignored. I can understand well that people are tired when they have written something, and do not like critical comments, it's the same for me. But what happens is that critical readers just vanish.
But actually the Nim documentation has improved a lot since 2014 when I discovered Nim.
For me the biggest problem for the Nim documentation are the few people who refuse to read and learn something and pollute IRC, forum and stackoverflow with stupid questions, because no one will ever be motivated to write fine docs when people refuse to read that. What we have to remember is that the few visible ignorant people are only a majority, as we do not see all the other ones which read docs carefully.
Another general problem are existing low quality docs, as they may block the better ones. I have seen such blockings for other FOSS projects too. There can exist low quality documentation, which no one dares to delete, to not make original authors angry. The Nim wikipedia entry is an example for that, one of the worst pages I have ever seen. Well the gEDA page was in a similar shape ten years ago, I rewrote it from scratch that time.
I know you had some tensions with some people in the community. Hope everything gets resolved. There's always some tensions when there's more than 1 person present, we can only hope it doesn't get reflected on the products of the work.
Fixed the link. You have some issues with the SSL certificate, btw.
Which kind of a table do you need for your use-case? What are the benefits of using this over other collection types? When shouldn't you use tables over other types available? How slow are the basic operations?
These are questions anyone who knows what a hash table is should be able to answer.
Yeah, as if answering those question in a couple of words is equal to an explanation of how Hash Table works. Let's not split hairs there. Also, there were real world examples in the same post you quoted me from.
What if a reader comes from Lua, for example, where everything is a table? How bad is it If the first thing he sees is a small table of comparison between different container types Nim provides in the standard library? How bad is it if tables mention there's a also BTrees in Fusion and one might consider using them instead for X or Y?
Don't know how to make myself any more clear.
What if a reader comes from Lua, for example, where everything is a table? How bad is it If the first > thing he sees is a small table of comparison between different container types Nim provides in the > standard library?
he will use it... as he did in Lua, Python, C++, Rust... depending on his background... without knowing how it works (or its properties), approximately in the same way as a housewife uses its microwave oven or a blonde ride a supercar. He will skip everything he does not take in, as housewife (blonde) will skip technical documentation about hers oven (supercar) .
Blonde and housewife jokes are not appropriate, please either edit or delete your post.
It is not a joke - it is reality whether you like it or not.. sorry
I remember when the "Edit" button on our documentation was considered to be so essential that poor Araq went ahead and implemented it. For years now we have this nice Edit button on everything. I think we got about 5 PRs in total more thanks to this button.
@araq the main use case (at least for me) of the Edit button is actually the Source button (they come in pair and having 1 or both is same complexity), which allows a 1-click jump to see the implementation when needed. This I use quite often.