I have been talking about Nim on Twitter/X recently, and I got this feedback right here:
Nope I'm giving up on NIM. Karax has bad documentation too. Nim seems like a cool language but the frameworks really, really suffer from lack of examples and documentation. view thread
It's one interested user, but it mirrors closely my own experience- while I was willing to put up with it because Nim has royally spoiled every other language for me, there was considerable friction getting over the sparse documentation in every area of the Nim ecosystem (the manual and compiler error messages have drastically improved since then).
I would like to talk about how you think we could improve the situation so new users face less friction. I have made a rule for myself to always open a ticket when I come across a usability issue on the compiler, and submit a patch when possible, but perhaps this approach should be extended to the ecosystem. I think it would really help if as many of us as possible made a mental note to at least open a ticket, and submit a patch if possible, on any Nim project you use, if:
Mind you, I don't want to badger everyone with a minor Nim project- I think we should focus on submitting documentation patches, if possible. Nothing crazy- just share the knowledge you are aquiring using a project if that hasn't been done before, it's not much more work to write your notes for the public in the readme. I'll start with Karax, it need a little something more on event handlers!
I think if we start doing this, new projects will naturally follow the good example set by the existing projects.
Do you think this is a good idea? Feel free to go ahead and do it, then :) If enough people like the idea, I think we could put up a sticky thread on the forum.
Do you have another idea? Please share it here!!! Thanks!
Regarding Karax, https://github.com/karaxnim/karax/issues/267 is more concerning to me. The documentation is "fine" in the sense that it suits the target audience which is Nim programmers who already like Nim and want to be shielded from JavaScript and a stateful DOM. It's not for JavaScript developers who do not understand anything and count the number of bytes in the produced JS code.
It seems to be a good idea to communicate this "target audience" much better.
Of course, PRs that improve the situation are welcome too.
Documentation is insufficient to get started (I tend to look at code a lot instead of reading documentation so sometimes I don't notice)
Not really actionable and it's the nature of the thing that e.g. strutils.replace doesn't tell you how to install Nim.
Examples aren't working
Inexcusable. Can be an outcome of not using nim doc which can ensure things compile&run.
Examples are too sparse or don't cover enough cases > Project description is lacking- summary, scope, use cases...
Maybe. I don't know.
Project is outdated or abandoned but doesn't make that clear
Well if it's abandoned then it's kinda the logical outcome that the documentation does not make that clear.
Curated-Nim lists point to projects with major issues
Most interesting. Somebody should keep this list up to date.
Examples are too sparse or don't cover enough cases
That's the main deficiency of the official docs, atm, imho. Especially the stdlib docs could benefit most from (way) more examples, I think.
Every programmer is a Nim programmer! They just might not know it jet ;)
In all seriousness- the existing karax documentation isn't even remotely up to the job of introducing Karax even seasoned Nim programmers. I just started a project and I have to look through the source all the time even for fairly basic stuff, like how to have a text input handler.
No fingerpointing!! I'm trying to mobilize help to improve the situation, not lecture you on the best use of your time. I don't think this is necessarily a problem that needs to be solved by you. Thanks for Orc!!!
As far as an correctly assessing the situation goes, I'm pretty sure you systematically underestimate the optimal documentation density by a factor of at least 10 even for existing Nim programmers, and that's just to reach 'adequate'.
As far as an correctly assessing the situation goes, I'm pretty sure you systematically underestimate the optimal documentation density by a factor of at least 10 even for existing Nim programmers, and that's just to reach 'adequate'.
You might be onto something here.
Thanks!!! I believe I am :)
Don't feel bad- it's normal. You know how at university, at a subject you're average at, it's so frustrating to go to a tutorial where the tutor is really, really good? They gloss over all the crucial basics because they think they're obvious.
I would however ask you to consider encouraging more people to help with documentation, even if the result looks mind-numbingly verbose to you. In fact, I think 'looks mind-numbingly verbose to Araq' would be a pretty good indicator that in documentation, we're doing well! ;)
Not really actionable and it's the nature of the thing that e.g. strutils.replace doesn't tell you how to install Nim.
No that's not needed, but the karax should show you how to install the package, run a hello world (it does some of this okay), but
Examples aren't working
Inexcusable. Can be an outcome of not using nim doc which can ensure things compile&run.
Examples are too sparse or don't cover enough cases > Project description is lacking- summary, scope, use cases...
Maybe. I don't know.
Yes. Positively. Trust me. It's a quick help for some guy cobbling together just enough code to share the best recipes for Chicken Tikka Masala, not a paper for best three experts in the world for the esoteric subtleties of quantum physics.
Project is outdated or abandoned but doesn't make that clear
Well if it's abandoned then it's kinda the logical outcome that the documentation does not make that clear.
You could put up a quick note... many do.
Curated-Nim lists point to projects with major issues
Most interesting. Somebody should keep this list up to date.
Oh I can do it right now: delete the list. Almost all of our projects have documentation issues by reasonable standards, except maybe jester, nimble and weave (apologies if you have a project with good docs I'm unaware of).
That's why I think it would be good to have a broader push to improve documentation across our ecosystem.
Oh I can do it right now: delete the list.
Heh, I think "curated projects" does not imply "projects with good documentation".
Documentation (and both teaching / writing in general) is a never-ending task with strong dependency / variation across target audiences & situations. Every year new kids enter kindergarten. :-) One can always try to be better / reach more, but there is also almost never "one level". E.g., university courses have prerequisites.
Doc patches are also one of the both easiest & best ways for new people { "The Recently De-confused" :-) } to contribute to any project / document / tutorial. So, curated packages could indeed be "packages 'but for' erm.. 'good' documentation!" - an implicit solicitation for help explaining anything unclear (but valued by some that found little more needed to make the list).
None of any of that is very Nim- or Nim-ecosystem specific, though. Just part of living in the world with others, as is trying to coach/coax impatient people on Twitter / "The Internet" to be more patient as @Vindaar & @cmc did on that thread. Sadly, that, too is a never-ending task - and not only in computing.
To be more concrete on this eternal topic, maybe everyone with Github (or similar) projects should use their Wiki feature (or similar) more?
Another thing I want to add is that I would love to have offline Nim documentation. GNU Info is a great format for writing book-sized manuals which can be read directly from within the editor. Info is normally generated from GNU Texinfo files, but it should be fairly straight-forward to generate Info files from some other source.
Online-only documentation has three main problems:
GNU Guile is an example of a language that includes a full offline copy of its manual in Info format. I am not saying that Nim must use Info, but it would make sense to at least offer it as an option because we could piggy-back on the existing tooling.
As for libraries, nimble could provide a nimble doc command which would open the manual of the library. Maybe have a format option, so the user can do nimble doc foo --format=html or nimble doc foo --format=info depending on which format he prefers. Nimble only needs to return the path to the manual file, the user can do whatever he wants with the path, like run xdg-open $(nimble doc foo --format=html) to open the page in a browser.
What a pointless comparison.
It was answer to "they have introduced new syntax (e.g. .jsx or .tsx)" - I showed that in JS it's possible to do something like Karax.
P.S.
I have nothing against Karax DSL, and actually, in past used similar HTML DSL called HAML. My past criticism about Karax was about things like`tdiv`, lack of infer for func arguments, like onclick, and some other inconveniences.
Mastering Nim is a pure reference book with some opinionated boxes sprinkled in.
While the reference part is easily the biggest part of it, there are other useful parts which contain examples and explanation.
but nothing that forms a coherent guide like K&R C does
It's easier to describe a language released in 1980 than one released in 2010+ after 30-40 years of technological progress and growing user expectations.
There are chapters on mastering macros and parallelism, I have not yet made it to those, but those are advanced topics for people who already have a good grasp of the language fundamentals.
Well that's the chapters that I mean. The fundamentals are the things you are supposed to know already as the book's target audience is experienced programmers.
I don't know where this aversion to writing documentation comes from.
"Read the source, Luke!".
:(
That's a really neat theory about documentation aversion. Reading your explanation, I got a hunch that maybe it's because considering others emotionally is built-in, while considering others cerebrally is rather hard work that can lead to overthinking and other problems so people throw in the towel.
There seems to be broad agreement that good docs contain tutorials, how-to guides, and a reference. I've never heard about explanation mentioned separately but it makes total sense- I'll add it . Your rationale for having tutorials sums it up nicely, adding that as well.
Hahaha yeah, another Supercollider user! I learned the hard way to read the source instead of the docs using SuperCollider! It worked wonders for Nim as well! I know what, we'll just scrap the whole documentation thing and have Nim marketing exclusively target SuperCollider users, then we can cut out about two thirds of the manual as well.
SuperCollider-style offline docs is a great idea- this ties into tooling, having docs while typing seems to be rather popular, I'm assuming vscode doesn't have this yet for Nim.
Hahaha yeah, another Supercollider user!
I do extremely silly stuff in it, nothing like "music" and the "hundreds of levels" deep OOP drive me nuts. Everything points to everything ...
If we put the docs & tuts in a "universal" format in a small db, SQLite, DuckDB, others, one could do versioning, create time lines for subjects, updating the docs with a query, add library docs in a proper way so they can also be removed. It would give full text search. Then a query engine and a doc renderer for various formats. A nice thing can be to have links point to several location options (hover over accuracy @ https://wiki.povray.org/content/Reference:Keywords )
Then there is this other thing, sorry for the wording, web search engines _suck nowadays. In all my searches on "how to ... in nim" Tomohiro's Nim FAQ https://internet-of-tomohiro.netlify.app/nim/faq.en never turned up. That is sad. Is there a way to improve this, without building a monolithic Nim silo that contains everything? Are all the other communication channels besides the forum searchable? (I only use the forum)