A serious issue that we should seriously address in 2023 if we really want Nim to grow, is the documentation. Nim is one of the easiest system languages to use, but one of the hardest to learn. The only way to learn the language is to read the manual which describes the entire language in a single web page ! An then to read the do of each module, which is a simple list of procs with two lines of comments and a runnableExample.
This is my suggestion, we should create a documentation committee with a dedicated forum of discussion space. This group will write a new documentation for the language, that will be easy to read, comprehensive and multilingual.
And since Araw and the rest of Nim community leaderboard are already too busy on the source code, we should all contribute at least a bit on such a project. I'm francophone, and I will be so pleased to translate the docs to french ! In fact I would do anything to make the project succeed if it was validated.
we should create a documentation committee with a dedicated forum of discussion space
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. It does not require a committee to figure out what is wrong, it requires an environment that makes it
Nim-lang conducts a yearly community survey with results available on the blog. 2021, 2020, 2019, 2018, 2017, 2016. Some questions persisted over the years.
“Top/High”, “Medium” and “Low/Ok” priority
| Question | 2021 | 2020 | 2019 | 2018 | 2017 | 2016 |
| Documentation | 40/36/24 | 42/30/28 | 50/26/24 | N/A | N/A | N/A |
Documentation quality is steadily improving year-over-year.
There are also multiple books you can buy to learn the language, it sounds like you're not aware. In addition to that, there is:
https://nim-lang.org/documentation.html
covering:
"Nim by Example"
"Learn Nim in 5 minutes"
"Tutorial part 1"
"Tutorial part 2"
"Macro tutorial"
"Nim for Beginners"
"Nim Days"
"Nim notes"
Be specific, what were you trying to accomplish where you found the documentation lacking?
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.
Well what I mean is that somebody learns Nim, they may struggle a lot to gather all the information necessary to be a really efficient developer with the language. The manual just summarize each part of the language. If you want to go further, all what you have is a list a procs with few lines of comment. That is very painful way to learn.
Let's take an example, if I want to learn to use threads in Nim, all what the official doc give me as explanation is here: https://nim-lang.org/docs/manual.html#threads. It just takes three to four paragraphs. After that, I have to manage by myself to understand the modules threads and threadpool. It's not too hard to understand what each proc does, but to put all that together and really understand how parallel programming works in Nim...
Few days ago, I opened a thread, on this forum just to ask about a detail in std/logging, because there was no explanation about it in the docs.
Yes, that is a good example because it is a lot more actionable. I did a search and apparently there are no open issues related to documentation content https://github.com/nim-lang/Nim/issues?q=is%3Aissue+threads+label%3A%22Documentation+Content%22+
Doing a quick search on google turns up a paywalled piece of the "nim in action" book https://livebook.manning.com/book/nim-in-action/chapter-6/16 but I don't think anyone starting to learn a language would be thrilled about spending $20 on the book (it is discounted now, usually it is $40) or $62 https://www.amazon.com/Mastering-Nim-complete-programming-language/dp/B0B4R7B9YX/ref=sr_1_1?crid=27JR555Q4SQ8K&keywords=mastering+nim&qid=1666896008&qu=eyJxc2MiOiIwLjIzIiwicXNhIjoiMC4wMCIsInFzcCI6IjAuMDAifQ%3D%3D&sprefix=mastering+nim%2Caps%2C229&sr=8-1 "only physical" no matter the amount of advertisement by the authors.
So your specific complaint about the "threads" documentation, and similar instances, are the main starting points for the documentation improvements. I haven't done any thread-based programming in nim (nor async for that matter), so I can't provide any suggestions for what might be added into the documentation (since I don't have any requests that would be based on my experience), but you can just list things that you would want to see there, or things that you had to search elsewhere.
So to summarize, what I'm sayin is:
Sorry but the links on https://nim-lang.org/documentation.html are not sufficient at all. And nobody have to pay, to learn other languages.
Just put yourself at the place of somebody that is new to Nim and tries to understand how to create a http server in Nim. You will see very quick what I'm talking about.
The asynchttpserver module doc just have a single paragraph and a runnableExample, with a short list of procs. How far can someone with so few information ?
To be honest, the few of Nim that I know, I learned them by reading Dr Salewski's book.
Few days ago, I opened a thread, on this forum just to ask about a detail in std/logging, because there was no explanation about it in the docs.
This one https://forum.nim-lang.org/t/9760#64260
Can
There is the logrotate tool on many *nix systems and i think the RollingFIleLogger is supposed to mimick some of it's functionality. What it does is explained in detail in man logrotate. The purpose is, as Cnerd says, to periodically check the current log file and rotate to a new one if certain criteria are met (i.e. file size, age). If you would not rotate the log it would grow infinitely.
be adapted, pasted in documentation directly? You can PR the answer || open an issue with documentation improvement (maybe you personally don't have time/bandwidth to implement the PR, but there is someone else who does, but they are not aware of the opportunity, so you can play a relay role to bridge supply with demand in here)
considering how much Nim offers, the existing documentation, especially the official one, is absolutely ridiculously minuscule
If Nim would have at least a hundred times (...) the amount of higher quality documentation, I guarantee, that the user base of this language would skyrocket, compared to how it's going, now.
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.
Sorry to repeat your words, but waouh! It's just like you reading in my mind ! That's all what I'm trying to say since the beginning.
@Araq, why not give a try to a new documentation project ? What will it cost ? Why is it so hard to break to status quo ? We all want Nim to progress right ??
The manual is also available as a PDF.
When I say that we can't learn a lang with a single page, I'm not talking about the way it presented, but about the length of the content. Everything is summarized in the manual, to fit it a single web page.
There is not ONE place online, where you can learn ALL what is possible with Nim.
But https://nim-lang.org/documentation.html comes close.
There is also https://nim-lang.org/docs/theindex.html, I do search for "server" and it points me to https://nim-lang.org/docs/asynchttpserver.html which contains:
import std/asynchttpserver
# This example will create an HTTP server on an automatically chosen port.
# It will respond to all requests with a `200 OK` response code and "Hello World"
# as the response body.
import std/asyncdispatch
proc main {.async.} =
var server = newAsyncHttpServer()
proc cb(req: Request) {.async.} =
echo (req.reqMethod, req.url, req.headers)
let headers = {"Content-type": "text/plain; charset=utf-8"}
await req.respond(Http200, "Hello World", headers.newHttpHeaders())
server.listen(Port(0)) # or Port(8080) to hardcode the standard HTTP port.
let port = server.getPort
echo "test this with: curl localhost:" & $port.uint16 & "/"
while true:
if server.shouldAcceptRequest():
await server.acceptRequest(cb)
else:
# too many concurrent connections, `maxFDs` exceeded
# wait 500ms for FDs to be closed
await sleepAsync(500)
waitFor main()
And these examples are guaranteed to compile&run because the infrastructure ensures that. And this is all available for free, not to mention there are internet search engines and AI bots that can write Nim code for you.
But no, we need no less than a new documentation task force that writes yet another book. For whom? For the people that are already overwhelmed?
This is ridiculous.
I do feel that beginners (as in, less experienced programmers, people who haven't used many languages, not all new nim users) might find this style of documentation intimidating, because there's not much hand holding.
Well that's why the two kinds of doc have to cohabit. As I said in a previous message, the docs of the modules are very detailed. They should remain and only have to be improved.
But there should also be a real official tutorial.
Nim was not designed for beginners.
I thought we were here to make it convenient for everybody ! What a disillusion for me !
don't use what you don't understand" goes a long way. You can write programs successfully without templates or macros
So to make things simple, many features in the language (all the ones that are under-documented) were built for the core Nim team, those that already know how they work. If you are new two Nim, even if you are not new to programming, you have to manage to do everything with if and else. And if you are not satisfied, then try Zig !
But https://nim-lang.org/documentation.html comes close.
It's not one place to learn, but links to many places, many non comprehensive resources.
it points me to https://nim-lang.org/docs/asynchttpserver.html which contains:
That runnableExample and few paragraphs are basically all what the official docs teaches us about something as wide as developping http servers. So I don't use an external tool, or if I want to develop one, those few line are all what I have to rely on to implement, distribution, micro-services, etc...
For the people that are already overwhelmed?
What is overwhelming in Nim docs, is not the quantity of information, but the way they are scattered between tones of partial resources. I'm just proposing to unify all that.
I thought we were here to make it convenient for everybody ! What a disillusion for me !
Same for me, I thought you at least know how to use your browser.