Although I am personally quite happy with Nim's documentation, I can see sense in your arguments.
Here are a couple concrete changes that may improve the usability of the documentation: * Group overloaded functions under the same header. Split should be one entry with its purpose and usage described upfront, before implementation details. * Maybe the Nim community should draw inspiration from or even embrace [Sphinx](http://forum.nim-lang.org///www.sphinx-doc.org/) as the documentation tool. Nim support could be added via [domain](http://forum.nim-lang.org///www.sphinx-doc.org/en/stable/domains.html) and by developing an autodoc extension.
