The reason why i mention separate pages Araq is not because its waste of time but because it allows Google & other search engines to directly link to the answer people search for.
The Foo example you write above is indeed a wast of time. Its a wast to even document that because its useless. The idea of user friendly documentation is directly point to the information the user needs. Explain in detail what it does. What each function calls that a object has does. One or more examples for each and all. I simply used the "split" as one easy example of just bad documentation flow. I come bearing examples: [http://nim-lang.org/docs/selectors.html](http://forum.nim-lang.org///nim-lang.org/docs/selectors.html) Do do please tell what that does? If i did not have the code as a example, you will not know what to use that function for. [http://nim-lang.org/docs/threadpool.html](http://forum.nim-lang.org///nim-lang.org/docs/threadpool.html) Again ... if one does not know its part of the async code or finds a example of its usage. Good luck using it as a non-initiate. Example usage? _lol_ ... where ... Those documentation are written by people who know the ins & outs of the code and more or less write the documentation for themselves. Nim when you understand is not ultra hard ( sometimes ) but lets be honest, it puts a 1000f wall in front of people. It starts to feel more like trying to learn Perl. When you know it, its not hard. But it simply scares away people in droves. And it bothers me a LOT running into these constant problems because the language is good Araq but its so unfriendly to learn ( from the documentation ) if you have very little experience or come from a _kuch_ php /vb / whatever background. Focusing on the obvious is what brings in new people. Making it easy to learn. Edges cases etc are things that people need to stumble upon or needs as "extra's" in the documentation. But simply dumping the most problematic answer in front of people and say: "He, learn from this". People there answer is: "I go somewhere else". Said it before, marketing. The biggest fail of many products. And Nim is a product. Too many underestimate the market. You think that people will register and post how they do not understand your product or get too fast stuck in it. A lot simply quit without saying a word or give up. Let me use the restaurant analogy. Why do a lot of restaurants not understand why people do not come back. People have a less stellar experience, and simply move on to the next restaurant. But they do not tell the restaurant because they do not want to look bad. They simply vote with there actions. There is still a lot of work left to make it a more attractive product ( especially compare to some of its competitors ). To put it in simple terms, you can make the most advanced car in the world but if it takes people too long time to read the manual & drive the car, they will simply prefer a Volkswagen beetle instead. Anyway, my monthly rant limit is reached with this i think. ;)
