@kylrth Thank you for starting this topic! I want to dive a little deeper into your comments if I can.
The User Guide is for explaining implementation patterns, I think. With the way it’s set up now, reading through from beginning to end is not very appealing. I think it’s too disconnected from the examples and tutorials.
In my mind, the major failing of the User Guide currently is that it is lacking cross references to complete examples, and to the ref guide. I think many/all of the narrative sections with snippets should cross reference to relevant complete examples, and/or reference docs sections.
I don’t necessarily see the Users’ Guide as something that anyone would read through start to finish. Rather I see it as organized by topic, so that it can be useful for users working in a given topic area.
Roughly speaking, in my mind:
Tutorials These are intended to be start-to-finish, in order to bootstrap getting users both the big, high level picture, as well as the most important conceptual context
User Guide Topic-based. You go here when you want to find out about Handling Categorical Data but it’s not necessarily something everyone would read start-to-finish, because many users won’t care at all about some of the topics.
Reference Guide For experienced users to look up specific information they already know something about (but just need some detail or other)
Does this seem reasonable? Are there other points of view on this breakdown?
The reference was useful once I understood what it was. Navigating through the class hierarchies was sometimes a pain. There was no single location listing all the attributes of a single class.
This is not the first time this has been raised, and I am not at all unsympathetic to the view that the Reference Guide needs:
- more information per entry, as a rule
- more entries repeated (so users don’t have to follow inheritance hierarchies)
There is a Sphinx option to turn on showing all attributes on all classes (i.e even all inherited ones) The only reasons I have resisted this are:
The ref guide has often has lots of classes per page. Turning this option on trades one problem for another in my mind: now you have a “needle in a haystack” situation because individual ref guide pages become enormous.
There are a lot of somewhat internal attributes that are really just noise for regular users.
To address this I would propose:
- Splitting up the ref guide more discretely, maybe a page per class even
- Creating a way to mark “advanced” or “developer” options so those can be hidden, or at least hidden by default.
I should add, the Bokeh docs should be migrating to ReadTheDocs soon, which should also restore the site search. I think my first objection above is ameliorated quite a bit when that becomes true.
Some things I might propose:
- Make is so that examples can contain a narrative doc string that gets displayed on the example page
- Make is so that examples can state cross-reference terms that get added to the index, and make it easy to reference examples from user guide sections.
- Implement the two reference guide ideas above, and turn on the option to show all properties for all classes
- Add more cross referencing to reference guide from user guide, maybe even automatically (there was a PR for something like that sadly fell out of date before it could be merged)
Thoughts on this? Thoughts on other ideas?