On Friday, October 04, 2013 16:12:14 Craig Dillabaugh wrote: > I guess the more fundamental question is, what is the purpose of > the documentation? Is it a quick reference for D users, or is it > a resource for people trying to learn the language? I learned > C++ using Qt, largely from their online docs. The Qt > documentation is a reference, but it also tends to provide lots > of explanation.
It would never have occurred to me that API documentation would be use for teaching the language - even documentation for the standard library. I would expect people to learn the language first. Yes, the standard library documentation needs to be reasonably accessible to newbies, but I would not expect it to be used as a teaching tool for the language. The documentation on a type or function is there to teach you about how to use that particular type or function, not how to use the language. Of course, I'm also the sort of person who thinks that people are nuts to just jump into a game without reading the entire manual first. - Jonathan M Davis
