I feel like a parrot but taking this for example > A good example of the style of documentation that makes things difficult for > beginners is the ‘Iterators and the For statement’ section in the Nim manual. > From a beginners perspective this might be better presented as two sections, > one about the For statement, the second about iterators and their use in for > loops to enable ‘for each’ style loops.
The Nim manual is not a tutorial, it’s a reference and a spec. It does not solve the documentation need of “how to” it answers “what can be done”. So the primary audience of it is for people who knows that something can be done but they don’t exactly remember what to search for. Nim basics is a tutorial that approaches for loop in a beginner friendly way: <https://narimiran.github.io/nim-basics/#_for_loop> Reference: <https://documentation.divio.com/> > There is a secret that needs to be understood in order to write good software > documentation: there isn’t one thing called documentation, there are four. > They are: tutorials, how-to guides, technical reference and explanation. They > represent four different purposes or functions, and require four different > approaches to their creation. Understanding the implications of this will > help improve most documentation - often immensely. | Tutorials| How-to guides| Reference| Explanation ---|---|---|---|--- oriented to| learning| a goal| information| understanding must| allow the newcomer to get started| show how to solve a specific problem| Describe the machinery| explain its form| a lesson| a series of steps| dry description| discursive explanation analogy| teaching a small child how to cook| a recipe in a cookery book| a reference encyclopedia article| an article on culinary social history
