There was quite a bit of good discussion [in this forum
thread](http://forum.nim-lang.org///forum.nim-lang.org/t/2364) on the perceived
limitations of the Nim's documentation, and possible improvements (I don't
think it reached concesus on a clear way forward).
My question is this:
What is the best way to provide examples and/or links to examples?
Because
* library module documentation becomes **bloated** if it includes too many
examples,
and
* experienced users can read the documentation without needing examples,
but
* examples need to cover concepts (multiple libraries), not just one library
* newbies benefit from seeing worked examples
* the code in the libraries themselves provide some examples (usually in the
assertion testing at the end of the module, or else test files in the tests
directory provide examples, but these aren't always targeted toward providing
newbies with hand-held examples.
I am thinking that maybe the tutorials could be extended to cover big topics
with lots of examples, and the libraries could add links to these as
"examples", keeping library doco lean.
I am not saying the current tutorials don't cover some/all of these concepts,
just that it would be good to include a lot more example code.
Also the tutorials are focused toward "system" library concepts (quite rightly
so), but a lot of the concepts listed above are nimble modules (non-system),
and the documentation should also extend to these "major" modules in some way.
* * *
_This isn't about changing the Documentation system, but to add more "newbie"
help._
