One of the most frequent complaint about Nim is that it lacks proper documentation. For example, it is mentioned in 2017 community survey, 2018 community survey (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).
Nim documentation page currently contains links to 4 tutorials, 2 books, FAQ, Wiki (last updated in March 2018), standard library documentation, and manual.
Some general questions first:
The quality of standard library documentation varies from module to module.
The basic structure is this: First give the user an "overview" how e.g. Nim threading works. Then give him examples to show how it's done in Nim. Finally, have good docu for the language (which I find not great but acceptable) and the libraries (which I often find poorly docu'd).
I'm trying Nim for the first time, four days to be precise.
I had a couple of moments when I did not understand compiler messages. I did not know which places in my code to look at. With some luck I found good suggestions on the Internet. If I hadn't found these solutions I wouldn't be using Nim now. It's because when everything is new in a language one is not sure and not ready to spend hours thinking about the roots of a problem.
The first issue was about name conflicts of modules residing in different folders inside src (resolved with foo.nimble file in each sub-folder). The second issue was about import statement. I was constantly forgetting to import not only the module I use directly but also the modules for return values if I happened to use them.
I'm missing cross references in the Docs (https://nim-lang.org/docs). There are some, but I suppose it could be more of them. An example from PHP documentation with a See also section http://php.net/manual/en/function.array-merge.php
Some functions in Nim Docks have very short description.
To create projects with Nim I want to stick with the official package manager. I like Nimble for its simple config. It's not that convoluted as Webpack config. But I have not discovered how to use it for importing macros from my other projects. So videos demonstrating Nimble capabilities are in demand.
The language itself is very easy to adopt. I just use the part of it I understand. With time new parts are added. It is very good. You don't have to know much (read large chunks of documentation) to start using Nim.
Good modern documentation features are online code runners(https://play.kotlinlang.org), walk-throughs(https://www.haskell.org) and fiddlers (https://jsfiddle.net/) where you can share code snippets and run them in a browser.
I enjoyed rust's documentation a lot, both when learning the language and when working with it - here's a good example:
https://doc.rust-lang.org/std/result/enum.Result.html
There's also a book that goes over the trickier concepts: https://doc.rust-lang.org/stable/book/
Good documentation is also easy to write and allows the code to stay beautiful afterwards - for example, it's hard to document fields because the comment is expected on the same line after the field - there's usually very little room there to write good docs..
Perhaps the hardest thing to satisfy is that good documentation requires active maintenance - if you have that, the rest falls in place..
proc GC_ref[T](x: ref T) {...} # empty
proc GC_ref[T](x: seq[T]) {...} # empty
proc GC_ref(x: string) {...}
marks the object x as referenced, so that it will not be freed until it is unmarked via GC_unref. If called n-times for the same object x, n calls to GC_unref are needed to unmark x. Source Edit
proc GC_unref[T](x: ref T) {...} # empty
proc GC_unref[T](x: seq[T]) {...} # empty
proc GC_unref(x: string) {...} # "see the documentation of GC_ref." i.e. basically empty, tooThis, ladies and gentlemen is what I would call a major clusterf_ck and it doubtlessly results in many unnecessary problems, bugs, and trouble as well as to people seeing that, turning around, and walking away from Nim.
It's also an example of what I meant recently: it's next to worthless toying when ever new gadgets are worked on and being introduced while significant parts of the bloody vital core of Nim are between unusable and a lottery due to poor, ridiculously minimal, or even absent docu.
Unless, for instance, the C FFI is sufficiently (interpretation on the generous side, please) and properly documented (e.g. -> GC_ref|unref) we have no right to truthfully assert that Nim has a good C interface. (Hint: Araq recently said that the manual on GC_ref/unref is basically wrong).
Simple rule: if something isn't well documented it should be regarded as non-existing.
Finally, allow me to bring up another aspect in that context. "We don't do XYZ yet" is not nice but at least honest. "We do XYZ and we even do it well!" but then failing the user giving Nim a chance is an invitation to wasted time, disappointment, and sooner or later a seriously tainted reputation. Recently there was discussion here re. How to attract new users. Hint: Not pissing them off by making them waste their time and having to walk all over the place (official docu, forum, other web sites, source, etc) to find bits of (hopefully correct) information would seem to be a good start.
Hint: Araq recently said that the manual on GC_ref/unref is basically wrong.
And then I changed my mind, it's correct. For the default GC. It is a bad interface.
This, ladies and gentlemen is what I would call a major clusterf_ck and it doubtlessly results in many unnecessary problems, bugs, and trouble as well as to people seeing that, turning around, and walking away from Nim.
No, it's something that you personally seem to care about the most to the point we should stop all other development on Nim until this one issue is resolved. I'm sorry to tell you, you are not the center of the universe, people also work on what they need and what they think will help Nim succeed.
Unless, for instance, the C FFI is sufficiently (interpretation on the generous side, please) and properly documented (e.g. -> GC_ref|unref) we have no right to truthfully assert that Nim has a good C interface.
It is "sufficiently" and properly documented. Don't mix manual memory management and GC'ed memory management. As the manual says. As c2nim does it.
Simple rule: if something isn't well documented it should be regarded as non-existing.
There is nothing "simple" here, "well documented" is not an objective criterion.
Hi! Thanks for listening to the community and Good luck @miran (and everyone) in making nim better!
Documentation can be classified into
A. Nim documentation in general Nim documentation page 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 for learning how to do things in Nim? Do you find it useful?
. Have you used code practice sites like Exercism 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?)
5. Can you show us the examples of 'good documentation' (GD, later in the text) in other programming languages?
Rust and go really set the bar so high for the documentation quality
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 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) I disagree with the question, everything is in ongoing process for improvment.
To name a few modules I'm happy with os, osproc, sqlite
10. Are you willing to help making Nim documentation better? :)
I have noticed some improvement in compiler messages. But, I have a further suggestion. It seems, though I may be wrong, that when I hit some compiler error, it is because I don't understand the usage or syntax of something very particular - I still fumble over template syntax - though I do far more now than I ever did in C++ or D.
It seems that, since the compiler had an issue about something specific, that the compiler message itself might contain a link to the pertinent documentation for further edification. many terminals will launch a browser directly from the link on the console.
anyway... keep up the great work!! Nim is my goto language.
Other than that, reading this thread (esp. the "before" vs. "after") comparison, I realized I'm apparently already a beneficient of the improvements effort by @miran. I really appreciate your work, I found the quality of the contents of the stdlib docs quite good already, seeing the comparison I understand now it's mostly thanks to you - Thank you so much, Good Sir!!!
@akavel - you may (or may not) have noticed the "Group By Type" drop-down menu on the doc page for any given module (e.g. clicking on tables from theindex). That's sort of like what you're asking for.
The big theindex.html doesn't have that Group By feature, but perhaps should. The option there should maybe mean a multi-level sort -- first by the name of the defining module and then the way a given module would sort when in Group By Type mode. (Not advocating dropping the current order, just adding an option for that new one, too). You might want to create a github issue for that (if there isn't one already).
Also, I do see type signatures in https://nim-lang.org/docs/theindex.html , e.g. system: add(x: var string; y: char) . So, not sure what you mean there.
Also, I do see type signatures
But in the module docs there is no type signature, for example in
https://nim-lang.org/docs/tables.html#merge%2CCountTable%5BA%5D%2CCountTable%5BA%5D
there is proc getOrDefault() listed at the left under procs header at least 4 times, and that discontinouisly. I was never very happy with that, maybe adding type signatures would help?
@akavel - you're welcome.
@both - I'd have to agree that in a language like Nim which relies heavily on type-based overloads that long lists of the same ident in that side-bar/ToC section is not helpful. Right now each is a hyperlink to the specific one. So, collapsing would remove that choice, while including the signature would probably make them long and ugly. Not sure what the best choice to fix all that might be.
To the extent many use/advocate using just the big theindex.html to find things in the stdlib, adding GroupBy there might help. The core maintainers are very accepting of documentation upgrades. Someone passionate about the output/formatting should work on that or at least file a Github issue.
Hi, I just discovered Zeal browser and that made docs reading (like terrible GNU docs) less painful.
https://www.casimages.com/i/19032110495424237016167956.png.html
A VS code extension can open the docs from editor.
https://github.com/deerawan/vscode-dash
So why not saving Nim pages in a docset format ?
