Hi! Thanks for listening to the community and Good luck @miran (and everyone)
in making nim better!
Documentation can be classified into
* Soft documentation (clean examples, tutorials how to do X, or building
applications e2e this is a major factor)
* Hard (reference) documentation (documentation for every single bit in the
code) (nim makes that easy by just being static language)
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?
Run
As nim is growing and tackling various worlds frontend for instance a decent
karax tutorial can be promoted (i.e
[https://moigagoo.svbtle.com/exploring-karax)](https://moigagoo.svbtle.com/exploring-karax\)).
there're some [pleasent
writings]([https://scripter.co/notes](https://scripter.co/notes)) I'm not
actually aware of more sadly.
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.
Run
* Video is always amazing. 2 mins episodes talking about certain nim concept
or construct would be amazing
* Effective Nim guide (something like
[https://golang.org/doc/effective_go.html](https://golang.org/doc/effective_go.html))
* Howtos/Cookbooks
* Concurrency done right tutorials from concepts to some of well known
patterns. (e.g [https://gobyexample.com](https://gobyexample.com)
[https://doc.rust-lang.org/rust-by-example](https://doc.rust-lang.org/rust-by-example)/
[https://a-tour-of-go-in-haskell.syocy.net/en_US/index.html](https://a-tour-of-go-in-haskell.syocy.net/en_US/index.html))
* PyMotw like projects ([https://pymotw.com/3/](https://pymotw.com/3/)) but
I suggest that to be part of Nim modules itself not a separate project.
* Macros
* Concepts
* Contracts
* Selling dependency-free binaries? tell us how to build ones correclty
from the 100000 compiler flags there
* Selling javascript integration? take our hands into creating simple apps
with that
* Compiler guide I don't know what i'm supposed to be looking for in there.
3. Have you used Rosetta Code for learning how to do things in Nim? Do you
find it useful?
Run
I dislike rosetta code because of the way of browsing the code and it's kinda
dry
. 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?)
Run
I've, they're bit easy and approachable enough to get familiar with whatever
language you're practicing. It'd be great if we can coordinate with those
platforms.
5. Can you show us the examples of 'good documentation' (GD, later in the
text) in other programming languages?
Run
I'm a big fan of the community effort to tame the user experience with Rust.
Rust is complex but it goes by (are we good enough yet?)
Rust and go really set the bar so high for the documentation quality
* Rust docs
[https://doc.rust-lang.org/book/index.html](https://doc.rust-lang.org/book/index.html)
and for who doesn't want to read hundreds of pages
[https://doc.rust-lang.org/rust-by-example/index.html](https://doc.rust-lang.org/rust-by-example/index.html)
* Go docs [https://golang.org/doc](https://golang.org/doc)/
* Python docs are okaish
([https://docs.python.org/3/](https://docs.python.org/3/)) I use pymotw lots.
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?
Run
For modules in ideal world I expect
* Gentle intro to the module
* Detailed code intention for each part
* every proc, type, constant to be documented even if then name is clear
* combined with tests for both each proc and a general test on how the module
is intended to be used
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?
Run
* threading (no clear way on how to use)
* peg
* pcre or we should be use re? or peg all the way? i'm confused a bit.
* testing
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? :)
Run
I'm trying to help out as much as I can :)
