Re: RFC: How best to provide examples for newbies
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) _???_ | |
Re: RFC: How best to provide examples for newbies
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](http://forum.nim-lang.org///nim-lang.org/docs/db_sqlite.html#examples)
Re: RFC: How best to provide examples for newbies
I have added [a PR](https://github.com/nim-lang/Nim/pull/4571) 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.
Re: RFC: How best to provide examples for newbies
> (when a PR is raised, where should the rst files be located?) Just pick something sensible and PR away. I would name it `xdocs`.
Re: RFC: How best to provide examples for newbies
I like how examples and function descriptions done [here](https://clojuredocs.org/clojure.core/reduce)
Re: RFC: How best to provide examples for newbies
You're missing that RST supports `.. include:: moredocs.rst`. So we can keep the doc comments slim and yet can add many more examples for every proc in the stdlib. :)
Re: RFC: How best to provide examples for newbies
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: * Doc generator creates for each function a file ( araq already not going to be happy _lol_ ) with the basic information. Example: module/function_base.html * Doc generator creates also a "master" file. Example module/function * Wiki pages are created for each function. 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** * Clean source code ( no need for examples etc in the source ) * Simple to maintain source documentation * Website documentation is expandable & maintainable * Upgrades in the code documentation can be reflected in the website documentation without any danger that it will destroy the layout / interfere with the wiki content.
