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) _???_ | |
