As was made clear in the community survey results, many see the Nim documentation as being an area for improvement.
I recently started a project to work on this exact area, by creating a version of the Nim guide/tutorial as a GitBook. There are several reasons this is advantageous in my eyes:
I've only just started this project so far, but have a couple of early sections available. There's a live version available here: http://nim-docs.euant.webfactional.com/index.html, and the code is all available on GitHub, here: https://github.com/euantorano/nim-docs.
I'd be interested to know what people think such a guide should cover, and in what kind of order. Ideally I'd like it to be able to serve as a complete introduction and I plan to cover both beginner topics (what is a variable, what is a procedure/function, etc.) and advanced features that make Nim what it is (templates, macros, etc.).
I'd welcome any kind of feedback or contribution on this - would anybody actually se such a version of the guide/documentation? If you were/are just starting to learn Nim, would this kind of guide be useful? I'm aware I might be stepping on @dom96's toes slightly here given his existing book, and I don't intend to draw any focus away from that ;)
(Maybe the following should be a different thread?)
To improve the documentation
Being a someone who is kinda new to the terminology of computer science i find that in nim the documentation may be perfect for seasoned people who have a clue, but i did not at first. Till i started searching individual topics like, hygenic macros and such.
So my suggestion to add to this is that while maybe, documentation that approaches the novice or noob have an appendix of the explanations of the terminology that is used in the documentation on this website. I wish i would have had it, and maybe i still need it? i dunno, i like all the ideas here and would like to help but i am not self confident enough to volunteer yet.
i like jlp765's idea of a periodic "lets figure this out together moment". maybe based on problems people from other languages who do not know nim so well like me, need to know.
For instance maybe pointer arithmetic... its different in c than in nim to do it. i think without someone like Araq showing how to do it would be a challenge to say the least, for me at least i know!
But in the same though maybe a category like "coming from c to nim" or "from python to nim" would be good. i think some stuff is like that on github already.
My plan is to include some kind of glossary of terms with some simple explanations and links to relevant areas of discussion. I also plan to ship some examples of usage with the documentation I'm writing too.
@jlp765 Yes, I think a roundup/review of what needs improving in the documentation every so often could be immensely useful. I can't contribute too much to the core or standard library or such due to time constraints, but editing a paragraph or two o documentation a night is something I can easily do (and I suspect others are in a similar position). Knowing what to focus on would definitely help and is one of the ideas behind this topic.
@euant
Its great you want to contribute with documentation.
Gitbook seems to be a locked in service. Django Framework is an example of fantastic documentation for an opensource project and it uses RestructuredText and Sphinx which are both opensource and self hosted. The documentation presentation for Django is great but the real value is in the comprehensive nature of the documentation and the completeness.
Documentation seems to be improving lately for Nim which is fantastic. For me presentation could be improved but there is still documentation that is terse and incomplete. I would like to learn more Nim and if I had time I could put in more effort to look through the codebase to discover how things work, but I simply don't have time.
Easy to use, and complete documentation makes a project more attractive and also more credible.
I added some more comparisons to the Nim for C programmers if someone can sanity check it (Comments, var parameters to procs, simple casting).
I looked at the Nim for Python programmers and wondered whether the tuple syntax example were correct (I thought it should be round brackets not square, except when defining a tuple[] type).
@honhon: Actually, GitBook the tool is open source, but GitBook the commercial hosted company is not. We would be self hosting the actual generated documentation rather than using their hosted service :)
And yes, Django has some of the nicest documentation I've seen. I'd love to see libraries and the standard library documented in such a way, and it's definitely improving recently which is excellent! This project is more aimed at the tutorials than the library documentation, similar to Django's tutorial.
@jlp765 I would look at it, but I've never actually written much C and doubt I could offer much advice/help on that front I'm afraid!
Anyone can raise a PR, but my perception is that very few do so
I think an "Edit me on GitHub" ribbon on the online copy of the docs could help.
a periodic "lets figure this out together moment".
Some other projects are running monthly conference calls to improve communication across contributors and encourage new people to join.