There was quite a bit of good discussion in this forum thread 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
and
but
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.
Said it at the end of that topic, we need to look more towards a WIKI example.
Code: Basic functionality + Link Website: Basic functionality + expanded information + examples + searchable/link-able by google etc
Website Documentation Wiki
[Basic information produced automatically from the code doc generator] [Extended information from a wiki]
How to:
This master file ( module/function ) simply does:
Include function_base.html Include wiki documentation function...
The site uses only the master files for searching, index etc.
Advantages
@Araq
is there a particular location that "worked examples" should be stored? (when a PR is raised, where should the rst files be located?)
They aren't a tutorial, or library document, per sae.
I also assume that example code may apply to a number of different library modules, if demonstrating a concept rather than just a specific library function, so a mechanism like .. include:: moredocs.rst is just what is needed :-)
(when a PR is raised, where should the rst files be located?)
Just pick something sensible and PR away. I would name it xdocs.
I have added a PR with two examples
When consensus is obtained as to the look/feel/layout, then the question will be what examples or topics need to be added.
As far as examples are concerned we definitely want to have more of them, but they need to be short. I have already said this in @jlp765's PR. Take a look at these for example: http://nim-lang.org/docs/db_sqlite.html#examples
Edit: in fact, in that link the Larger Example is too large for my taste as well, it needs to be more focused IMO.
In the PR, @Araq called this the beginning of a "Nim cook book"
So I will refer to this RFC as a "cook book".
I see the documentation options as complementary, not mutually exclusive. Here is a summary of what I see as some of the pros & cons.
| Documentation type | PROS | CONS |
|---|---|---|
| Nim Manual | THE reference for each proc() in a module | Examples are proc based, not task or concept based Doesn't show examples that span multi modules to achieve a task |
| Nim Tutorial | A newbies guide to the Nim language | Not concept or task based Is language rather than code task based (as it should be) |
| Nim In Action | Can provide a physical book for reference purposes Starts at the beginning and builds up to complex concepts (covers newbies to more advanced) A logical and ordered layout, can read chapters on specific topics, search via the index, ... | Doesn't cover each module (or not in the depth that the manual does) Needs to have focused examples Covers concepts well (but not extensive code examples except as appendices ??) |
| Rosetta Code | Easy to compare different languages Helps newbies learn Nim by code comparison of known language to Nim Is aimed at cut-and-paste then modify Lots of specific tasks/concepts provided | Not part of nim-lang site |
| Nim Cook Book | Can have verbose examples (cover concepts and tasks as full-worked examples. Is aimed at cut-and-paste then modify, to get newbies started. Covers the sequence of procs and logic to perform a particular task/concept (how to tie together procs/logic from a module to achieve a task) Provides coding style re-inforcement (when newbies use examples as the starting point ) | Is fragmented (not nicely ordered like a book). Multi-modules used in an example. Does the same thing as Rosettacode so is superfluous? (I argue not, as the cook book is more module specific, while rosettacode has lots of specific tasks for comparison purposes) |
| ??? |