Improving Examples and Documentation

> 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 versio

Improving Examples and Documentation

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 cu

Improving Examples and Documentation

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 t

Improving Examples and Documentation

> I don't know where this aversion to writing documentation comes from. "Read the source, Luke!". :(

Improving Examples and Documentation

> 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

Improving Examples and Documentation

Where? I am 100 pages in and it's still a reference manual (aside from the first part of course, but that's just about 30 pages). Yes, there are examples and explanation, but nothing that forms a coherent guide like K&R C does. There are chapters on mastering macros and parallelism, I have not y

Improving Examples and Documentation

> 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.

Improving Examples and Documentation

> 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 w

Improving Examples and Documentation

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

Improving Examples and Documentation

Documentation is a pet topic of mine. In my experience poor documentation is not so much a technical problem as it is a cultural one. Improving the technological side is good, but people who want to write quality documentation will always find a way, even if it is a plain text file check into th

Improving Examples and Documentation

See? Karax's DSL is better because it doesn't use goovy @ symbols everywhere... What a pointless comparison. Yes, I know you dislike Karax's DSL. But I like it, can you believe that. And all of that has nothing to do with Nim's documentation.

Improving Examples and Documentation

This is Karax buildHtml(tdiv): button: text "Say hello!" proc onclick(ev: Event; n: VNode) = lines.add "Hello simulated universe" for x in lines: tdiv: text x Run This is JS (CoffeeScript) with [simple implementat

Improving Examples and Documentation

I have worked with React & VueJs before, Honestly in those frameworks they either have their own template (e.g. .vue files) or they have introduced new syntax (e.g. .jsx or .tsx) but in Nim it was a lot more straight forward, just a macro called `buildHTML` and `VNode` type. The only confusion

Improving Examples and Documentation

Some of my coworkers have said similar things. They just need more examples to create good mental models. Also, I think making a doc build task a default would help. I have to lookup an example Nimble task everytime, so I often don't. It's silly since the tools are there, the project config inf

Improving Examples and Documentation

Yeah I don't mean to say we should do things the Python way- just be as effective. I'm rather fond of Nim's minimalism and terseness both in the language and the docs, I think 'comprehensive' is perhaps the most urgent need, both in scope and in detail. Why is testament internal use only? Would

Improving Examples and Documentation

I have created a github issue to serve as a central point of discussion and to hold sub-tasks, I will be adding the ideas from this discussion into sub-tasks in the coming days. Many thanks to everyone who participated and shared!

Improving Examples and Documentation

That's testament, a tool used for internal testing that has grown all the features we needed for testing. Much of it wasn't designed but grown. It's still better than unittest IME which is why I promoted it. I typically write custom test code though and often I don't need more than `when isMain

Improving Examples and Documentation

I think creating some sort of "mini org" in the vaguest of sense where you trigger "initiatives" that aim at a particular very specific thing and point out very explicit small things people could do. A lot of documentation inertia comes also from seeing the gargantuan task of "documentation" an

Improving Examples and Documentation

I've mentioned the Clojure docs multiple times in the past myself (not sure if here in the forum, but for sure on matrix/discord). I fully agree that something along those lines would be exceptional to have. Those are not a _replacement_ for better normal docs, but an amazing addition that can h

Improving Examples and Documentation

But @Araq, many of Nim's commonly used packages aren't documented at all- and I can tell that the ones that are fall short in very important areas. * They don't state in a nutshell what the package does, and when it should be used * They don't tell you how to get started, and if they do, the

Improving Examples and Documentation

Absolutely, that's what we should go for. If you want to go minimal, Starlette (FastAPI's little-known base) will do. I do suspect that you have the second part the wrong way around. I think part of why those examples are popular is because they put in the good documentation _first_.

Improving Examples and Documentation

I think the websites of projects like Vue, Flask, FastAPI, or httpx shows the ideal document amount of libraries like karax, jester, etc. When a Nim library is fairly popular, it should be slowly promoted to get as well-documented as those projects.

Improving Examples and Documentation

@cmc Yeh, Can.l is the great person behind owlkettle, all I did was provide the starting point for the nimibook and hook docs.

Improving Examples and Documentation

That is an **incredibly** good point and I completely blanked we had that. I was collecting a bunch of smaller doc changes (you may remember that I tend to do the odd doc PR here or there, most recent one e.g. slight expansion to the testament docs) and **entirely** forgot that button existed.

Improving Examples and Documentation

Arch Linux has the best technical documentation I ever encountered, full of copy/pastable stuff that comes from a comprehensive list of things you might want to do. Then you can add your own stuff from there. Fantastic. The documentation is a wiki! Pretty much like what you're proposing. Of cou

Improving Examples and Documentation

I have to admit that I actually haven't ever used the `Edit` button. However it only halfway solves the problem. You still need a fork on your GitHub, you still need to follow up the PR, and the PR of course still has to get merged. With the live-input system I propose you could just fire away a

Improving Examples and Documentation

> So you're the owlkettle guy? Owlkettle has some really, really nice > documentation!! He isn't. Isofruit/Phil works on mapster, snorlogue, ... While the creator of owlkettle is Can Lehmann

Improving Examples and Documentation

I agree that we don't have to please everybody, especially not everybody on Twitter (yikes!). However- this guy's reaction, strong interest in Nim and then outright disgust at the careless state of the docs closely mirrored my own, so it resonated strongly with me. I was almost that guy- I almos

Improving Examples and Documentation

So you're the owlkettle guy? Owlkettle has some really, really nice documentation!!

Improving Examples and Documentation

I believe the correct way to document such a button would be to have a little blurb: "How to contribute to this guide: Use the edit button to create a standard github pull request. We are mostly looking for contributions in expanded examples, but correcting errors is also welcome." I actually u

Improving Examples and Documentation

This would be absolutely fantastic. I'm _always_ getting my info from the sources and _never_ expanding the readme. This should be put into the subject "Documentation contribution friction" in our to-be-created documentation plan.

Improving Examples and Documentation

Yeah, you're right! That was pretty cool. I have this blog commenting module I made that looks pretty much like the PHP thing, maybe that's worth a shot. It's kinda like a minimal disqus but without an iframe. Docs were really not bad at all with PHP. The language kind of constantly picked at

Improving Examples and Documentation

> Can we form some group/sub-community (in some channel) which solely focuses > on documentation of the ecosystem? That is an excellent idea. I'm in!!! I think that group could formulate a vision for documentation in Nim (lots of ideas in this thread could go in), and then create a series of st

Improving Examples and Documentation

Yes!!! There is a very simple reason why examples are so important: They allow you to operate on inductive logic- deriving a general rule from special cases. Without them, you have to rely on deductive logic- creating your own special cases from a general rule. This is much, much harder. Someo

Improving Examples and Documentation

Yes it does! No it doesn't! Yes it does ;) I think it kinda does imply that. Right now it's kind of like a road sign pointing at a road block. Remember that 10x underestimation assessment of mine? This is one of those areas where you go against your instincts.

Improving Examples and Documentation

I remember spending time on an "Edit" button for the stdlib docs. The button still works. I got like one contribution in total thanks to this button...

Improving Examples and Documentation

Fair, but I still think the vast vast majority of people consume documentation online. So it makes sense to bring the contribution interface there. And of course, the best would be if we could get the library authors themselves to write docs. I try to document mine as well as possible (although

Improving Examples and Documentation

Commenting on docs and modules I really liked about the php (sic) docs back in the day's

Improving Examples and Documentation

In the days of old, I did a lot of process technology tests in an industrial environment. About 80% of the report on the results of tests was written before the test was done. How do programmers work? Imho documentation on libraries should be relative sparse, but still usable, readable and to t

Improving Examples and Documentation

Another reason to try to have better docs, _with [examples](https://forum.nim-lang.org/postActivity.xml#examples) (as well as commenting code well) is that it should help with LLMs learning more nim. In my experience they work pretty well with mainstream languages like python, but they hallucin

Improving Examples and Documentation

> Cloning a repo, writing half a paragraph about something, creating a commit, > creating a fork on your GitHub, adding your fork to the checked out repo, > pushing to your fork, creating a PR on GitHub, and then follow that request > up. This is not documentation specific and was one more reas

Improving Examples and Documentation

I totally agree with @cmc. I could write Nim forever, if I could. It's that addictive as a programming language. Documentation can be make or break the success of a technology. I think one of the reasons that Go enjoys success (though it's a boring language) is due to the availability of extens

Improving Examples and Documentation

I stand corrected, it was the fact that the docs were deploying with nim 1.6.10 and... somehow that caused some of them to show up? Can.l. fixed the problem and the docs are there again.

Improving Examples and Documentation

Jester has good documentation? I've had to read Jester sources far more than pretty much any other project.. That being said I really like the idea of improving documentation. One thing which I think will help immensely is an easy to use toolchain for Nim doc -> GitHub docs. Even something as s

Improving Examples and Documentation

Seems like something messed up the deployment for some reason, curious. I'll take a look at it given I wrote most of that dang book.

Improving Examples and Documentation

Maybe it's just me but when browsing the owlkettle documentation I got a 404 for for "6.3.4. Event Hooks"

Improving Examples and Documentation

Docs may be a good place for Nim users to contribute. It doesn't have to be written by core team. Also, ChatGPT / Autopilot may help, it's quite fun to work with :) P.S. I don't think that Nim needs better docs though, if you need to read a doc how to convert to JSON. Better docs are not going

Improving Examples and Documentation

Given how many folks had issues with jesters that I directed towards Prologue and that went "Finally, docs!" I'd say jester as well :-P Generally I try to slowly but surely get people to adopt what I deem as "gold standard" in my view: * doc comments on your public API and a github workflow t

Improving Examples and 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., unive

Improving Examples and Documentation

> Oh I can do it right now: delete the list. Heh, I think "curated projects" does not imply "projects with good documentation".

Improving Examples and Documentation

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 yo

Improving Examples and Documentation

> 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. C

Improving Examples and Documentation

> 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.

Improving Examples and Documentation

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

Improving Examples and Documentation

> 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 Inexcu

Improving Examples and Documentation

> 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.

Improving Examples and Documentation

Regarding Karax, 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 d

Improving Examples and Documentation

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](https://twitter.