In the days of old, I did a lot of process technology tests in an industrial environment. About 80% of the report on the results of tests was written before the test was done. How do programmers work?
Imho documentation on libraries should be relative sparse, but still usable, readable and to the point. For the latter, don't introduce other concepts in an example than the subject at hand. More smaller ones from a different angle of view work better. Again imho, every library (or group of related libs) should not only have it's docs, but also a tutorial. A tutorial in three levels. One level for for introducing to new users, one for mediors, one for advanced. The goal of the documentation as a whole should be that users hit the brick wall as late as possible if at all. For third party libraries, I'm sorry to say, I have many problems with those. Only pointing to the wrapped libraries doc, if at all. The incompleteness of many libraries (I can kind of understand). The linux-centricness of some. No linking from the docs to the repository. No linking from the repository to the docs. Having to dig through the source to get a vague idea what to do, or how it works. Nim is not simple/easy. Make 'the stuff' around it extremely accessible. @Araq I don't fit your user profile at all, @cmc remark on documentation density is spot on. Yet, I still appreciate all the effort you all put in the work you all publish very very much! Thanks.
