3 ms·

Author of the tutorial here. I didn't expect that somebody else might post a link to it - it seems I might be too late for the party. If anybody has any quest

Author of the tutorial here. I didn't expect that somebody else might post a link to it - it seems I might be too late for the party. If anybody has any questions regarding Nim or suggestions how to make the tutorial better - let me know.

airstrike 8y ago
If I may be so bold as to comment on form rather than function, I wanted to say I am not particularly fond of the typography / design choices for the tutorial. I know this is dangerously close to bikeshedding territory, but if I may, I wanted to point you to a similar resource that I recall being particularly pleasing to read way back when I was getting started in Python / Django: https://web.archive.org/web/20080730140551/http://www.djangobook.com:80/en/1.0/chapter09/ https://web.archive.org/web/20080730140551/http://www.django... That content has been retired from djangobook.com, and the website's design has followed suit, hence the archive.org link. I suggest also perusing the table of contents and making note of small design hints such as the use of color, whitespace, "Note" callouts, etc. At the very least, I hope you'll find this inspirational if you decide to take a moment to rethink typography, typesetting and the overall design of the website and PDF.
- narimiran 8y ago
  > I hope you'll find this inspirational if you decide to take a moment to rethink typography, typesetting and the overall design of the website and PDF. Thanks for the feedback! I would very much like to improve the looks of the website and PDF. The current situation is this: I have zero experience with html/css, so I just took some css template and tweaked some values (lots of trial and error) until it looked okayish (There is probably some unneeded stuff in there too). And PDF is created by using the default style of asciidoc-pdf - I guess this can also be customized, but haven't looked into it yet. Having said that, if somebody with more web-experience would like to improve my style.css [0], PRs are welcome. [0] https://github.com/narimiran/nim-basics/blob/master/style.css https://github.com/narimiran/nim-basics/blob/master/style.cs...
ModernMech 8y ago
I'm going to start this comment by saying I think this is a really good overview of Nim, and I think it's a good tutorial for experienced programmers who want a quick overview of the language. This tutorial is good for programmers who know how to program in other languages, and want to do so in Nim. But while I think the content is good, I think your framing is way off. You state explicitly up front that this document is not for experienced programmers, but for novice users and people unfamiliar with programming. You go so far as to assume they're so novice that they don't know what "printing" means in terms of text to a screen. I'm going to kindly suggest that this document won't be very helpful at all for those users. To illustrate why I think so, I'm going to walk you though reading this document from a true novice perspective: I'm reading the tutorial. I follow the installation instructions, and all of a sudden I'm installing over 500 MB worth of stuff to my machine? Many novice users may be coming from Windows, and some warning about this upfront would go over well. As a user who you assume doesn't understand even the basics of printing to the screen, you've asked me to download and install 500 MB worth of stuff just to run the compiler, and then you suggest I may need three additional tools (well do I or don't I?as your reader, I'm here for your opinion. I don't know the merits of any of these tools). It's more helpful to be authoritative in situations like this. Leaving too many options open for a novice user leads to confusion. But I persist, and I've downloaded your language tooling, MinGW, VSCode, assorted plugins and other things, and I don't really know what they're for. But after all of that, the payoff is to print a word to the screen. I would be a very determined reader if I continued at this point. But the remainder of the tutorial is supposed to take us from readers who don't know programming at all, to readers who can write programs. And the way you've chosen to do so is to introduce notions of types of data, and then build on that to the point where you are doing operations on data. That is a tried and tested pedagogical tactic for presenting new syntax to experienced programmers, but the novice is left fumbling and confused about what those data types are for and how that relates to the problems they'd like to solve with this language. You don't let the users write an honest to god program that has input and output until the very end of the tutorial. I'm sorry if I seem overly critical, but I think this tutorial could be much much improved if you just admit what it is (a tutorial exposing Nim syntax to experienced programmers), and reframe it as such.

airstrike 8y ago

If I may be so bold as to comment on form rather than function, I wanted to say I am not particularly fond of the typography / design choices for the tutorial. I know this is dangerously close to bikeshedding territory, but if I may, I wanted to point you to a similar resource that I recall being particularly pleasing to read way back when I was getting started in Python / Django: https://web.archive.org/web/20080730140551/http://www.djangobook.com:80/en/1.0/chapter09/ https://web.archive.org/web/20080730140551/http://www.django... That content has been retired from djangobook.com, and the website's design has followed suit, hence the archive.org link. I suggest also perusing the table of contents and making note of small design hints such as the use of color, whitespace, "Note" callouts, etc. At the very least, I hope you'll find this inspirational if you decide to take a moment to rethink typography, typesetting and the overall design of the website and PDF.

narimiran 8y ago
> I hope you'll find this inspirational if you decide to take a moment to rethink typography, typesetting and the overall design of the website and PDF. Thanks for the feedback! I would very much like to improve the looks of the website and PDF. The current situation is this: I have zero experience with html/css, so I just took some css template and tweaked some values (lots of trial and error) until it looked okayish (There is probably some unneeded stuff in there too). And PDF is created by using the default style of asciidoc-pdf - I guess this can also be customized, but haven't looked into it yet. Having said that, if somebody with more web-experience would like to improve my style.css [0], PRs are welcome. [0] https://github.com/narimiran/nim-basics/blob/master/style.css https://github.com/narimiran/nim-basics/blob/master/style.cs...

ModernMech 8y ago

I'm going to start this comment by saying I think this is a really good overview of Nim, and I think it's a good tutorial for experienced programmers who want a quick overview of the language. This tutorial is good for programmers who know how to program in other languages, and want to do so in Nim. But while I think the content is good, I think your framing is way off. You state explicitly up front that this document is not for experienced programmers, but for novice users and people unfamiliar with programming. You go so far as to assume they're so novice that they don't know what "printing" means in terms of text to a screen. I'm going to kindly suggest that this document won't be very helpful at all for those users. To illustrate why I think so, I'm going to walk you though reading this document from a true novice perspective: I'm reading the tutorial. I follow the installation instructions, and all of a sudden I'm installing over 500 MB worth of stuff to my machine? Many novice users may be coming from Windows, and some warning about this upfront would go over well. As a user who you assume doesn't understand even the basics of printing to the screen, you've asked me to download and install 500 MB worth of stuff just to run the compiler, and then you suggest I may need three additional tools (well do I or don't I?as your reader, I'm here for your opinion. I don't know the merits of any of these tools). It's more helpful to be authoritative in situations like this. Leaving too many options open for a novice user leads to confusion. But I persist, and I've downloaded your language tooling, MinGW, VSCode, assorted plugins and other things, and I don't really know what they're for. But after all of that, the payoff is to print a word to the screen. I would be a very determined reader if I continued at this point. But the remainder of the tutorial is supposed to take us from readers who don't know programming at all, to readers who can write programs. And the way you've chosen to do so is to introduce notions of types of data, and then build on that to the point where you are doing operations on data. That is a tried and tested pedagogical tactic for presenting new syntax to experienced programmers, but the novice is left fumbling and confused about what those data types are for and how that relates to the problems they'd like to solve with this language. You don't let the users write an honest to god program that has input and output until the very end of the tutorial. I'm sorry if I seem overly critical, but I think this tutorial could be much much improved if you just admit what it is (a tutorial exposing Nim syntax to experienced programmers), and reframe it as such.