I've tried to adhere to something similar to this for as long as I've written a library, and one of the great things about writing JavaScript libraries is that

I've tried to adhere to something similar to this for as long as I've written a library, and one of the great things about writing JavaScript libraries is that you can execute tutorials with live code execution inside the documentation itself. I wouldn't call it teaching per se, more of a framework for self-learning, especially for users who learn by example. I'd stick with the older saying "Show, Don't Tell," while making sure they can copy what you've shown. I think this is a simpler rubric: There should be at least two parts to documentation, API and Introduction pages. The introduction pages start off with a "First Contact" page and then delve into the myriad topics of the library (with a "Hairball" table of contents to explore if they please). These topics that may not all be relevant to a particular user, and ought to be as independent as possible. Ideally users should not be expected to read many pages before making sense of any other page. The API must contain definitions for every method and property, but should also make clear what the purpose of any particular class is and give a short explanation of common usage. The API should then link to the introduction so that common example code can be seen in action. Both the API and the introduction pages reference each-other constantly. For example in my library the Panels API page[1] contains several paragraphs outlining the purpose and common layout options of Panels, as well as (importantly!) linking to the associated introduction pages[2], where a user can see running code examples of common Panels, with code they can directly copy/paste into their own page to achieve identical panel layouts. The result should be something tightly coupled, with many links back and forth between introduction pages and the API, but the end result is not an actual wiki. I can understand the author's hatred of wiki's, because for most projects setting up a wiki is a lot like shifting responsibility for creating documentation to nobody. Which means it never gets done. (At for most projects I've seen and I think the author would agree. I'm sure there are a few great library wikis out there with nontrivial user-sourced content.) [1] Panels API page: http://gojs.net/beta/api/symbols/Panel.html http://gojs.net/beta/api/symbols/Panel.html [2] Panels "Intro" page: http://gojs.net/beta/intro/panels.html http://gojs.net/beta/intro/panels.html Compare these with, say, the Google Maps API page for "Map": https://developers.google.com/maps/documentation/javascript/reference#Map https://developers.google.com/maps/documentation/javascript/... Or worse, MVCArray: https://developers.google.com/maps/documentation/javascript/reference#MVCArray https://developers.google.com/maps/documentation/javascript/... There's extremely little about what it is, what is expected of it, and common uses of it. ~~~ If you write a JavaScript library, there is no excuse for not having live code examples and tutorials tightly coupled as part of the documentation.