Hi all, as promised here is a more thorough response. This is a very important topic and the input and comments are both valuable and appreciated. Here are some concrete things I would like to work towards:
* Add "dev/nightly" docs to bokeh.pydata.org
* Update gallery / split into categories / tag with keywords for index
* Improved / Curated index
* Better tutorial introduction / overview
* Server section in tutorial
* Hosted server examples in gallery
* Videos / Vines / Talks
Each of these points is explained in more detail below. I would love to have feedback on this list. Are there other concrete things that could be added to this list? Are there details below that could use refinement? Most importantly, is anyone interested in pitching in.
* Add "dev/nightly" docs to bokeh.pydata.org
I don't think we are at the point yet where we need to maintain docs for all releases, but we are at a point where there may be new and interesting things sitting in the docs on master that would be useful, except they can't be seen by anyone. I'd like to publish docs for the last stable release as well as a more-often updated set of "dev" docs...
This should be a very small and simple change to the docs fabfile and to the sphinx config for the docs.
* Update gallery / split into categories / tag with keywords for index
The gallery needs some love. I'd like to split it up into several categories. These need not be exclusive (i.e. a given plot could be in multiple categories). Additionally I would like to add keywords/tags to the plots so that they show up in the docs index (more below)
This is a non-trivial chunk of work. Most of the work would be to the current build_gallery.py, but also need to figure out how to store the meta-data about categorizations, keywords, etc. Additionally some design input to make the actually gallery pages attractive and highly functional.
* Improved / Curated index
There are alot of semantically useful terms like "linked panning", "linked brushing", "hover", "big data", that are actually illustrated in lots of places and especially in the gallery examples, but there is nothing to drive people directly to the information from the term. I'd like to add explicit entries into the docs index that cover these "human useful" terms and concepts.
This isn't hard work, but there might be a fair chunk of it, it requires human curation.
* Better tutorial introduction / overview
This is a pretty good example of why it takes more than one person/perspective to make good docs. I created the current tutorial for materials to deliver at conference tutorials, where I can others would be present to help the conferees, and where I also gave a separate introduction. In this capacity I think the tutorial is pretty exemplary (based on feedback) but it's clear that as a standalone document it could use some additions. There is already a GH to simplify the first few exercises to just use plain python lists, etc. and I think that is a good place to start. But also needed is an overview with a few complete examples inline.
It's a fair chunk of writing and organizing of thoughts and concepts. The best way to make this good is to make it a collaboration.
* Server section in tutorial
Long overdue, and long on my list. This can be another place to present and explain server concepts and also show how to use it for different use-cases (hosting, streaming, widgets, etc.)
Technically, this should not be alot of work, since existing server examples can be adapted to tutorial. But as above, it is a fair chunk of writing and would benefit from collaboration.
* Hosted server examples in gallery
This is an obvious and immediate need, it's really easy to talk about AR and plot hosting and server downsampling and apps and widgets, but what people need to actually use them are concrete examples that they can interact with and see the code for.
Since it will require hosting a bokeh-server somewhere, there are logistical details to figure out (where is the hosting, how is it funded, etc.) This is more a "people problem" than a technical one, several existing examples can probably be put in a gallery as-is once the infrastructure is in place.
* "Early" features marking
I don't like the work "experimental" it implies (to me) that the feature might go away. Typically the situation is that there is a capability exposed, but it may be incomplete, or subject to change, and as such is also probably not as well documented.
Should be trivial to add some banners to the current docs. Features I would consider early: bokeh.charts, Abstract Rendering/server downsampling, and widgets/apps. If folks have other opinions about what should be considered "early" that would be valuable input.
* Videos / Vines / Talks
Would like to have vines showing off features to accompany tweets about Bokeh. Would like to collect these on the docs, as well as links to youtube videos of talks and tutorials, etc.
Thanks,
Bryan
···
On Nov 10, 2014, at 10:34 AM, Bryan Van de Ven <[email protected]> wrote:
Hey guys, I have lots to add to this important discussion including some concrete proposals I would like to get feedback on. I've just got back from traveling and am pretty swamped but I am planning to give a proper response as soon as I can.
Short term message though: Bokeh can use any and all the help it can get, especially now that interest is growing. If there is anyone that would like to help but feels like there is something in the way of getting started (information, questions, whatever) please let us know and we will definitely work to get you up and running.
Thanks,
Bryan
On Nov 9, 2014, at 5:38 PM, Bryan Van de Ven <[email protected]> wrote:
Hi guys,
As always I really appreciate the feedback. I'd like to give a longer response to this, but I'v been traveling all last week. I'll have have more to say tomorrow!
Bryan
On Nov 8, 2014, at 2:43 PM, Tom Denniston <[email protected]> wrote:
I agree. Tooltips are a killer feature and a big reason to use bokeh
On Friday, November 7, 2014, Juan Nunez-Iglesias <[email protected]> wrote:
A big +1 to everything Josh said. I too have found it really hard to get started *and* almost everything in the gallery shows a simple plot with panning and zooming... Whereas I'm after tooltips, linked plots, and big data. (And I imagine many others are.)
And one related request: please purge "from bokeh.plotting import *" from everything. To quote Matt Rocklin, "Namespaces are a honking good idea. Let's have more of those." Not less!
On Sat, Nov 8, 2014 at 8:45 AM, Hugo Shi <[email protected]> wrote:
+1
the scope of bokeh is really big - I think we should in docs clearly
mark some sections as bleeding edge and experimental, and others as
robust, and focus on documenting the robust parts for now. I think that
would be manageable as the other sections evolve
I would consider the plotting.py API to be stable and robust (once
bryan's PR is merged) for the file/notebook/server backends
However I would keep bokeh.charts and all widget stuff, along with the
abstract rendering/server side data stuff as experimental for now.
What do you guys think?
On 11/07/2014 04:40 PM, Josh Wasserstein wrote:
Hi,
I keep hearing from colleagues and friends that it is difficult to get
started with Bokeh. The most common comment I hear is that, while the
gallery and the capabilities of the package look certainly
interesting, the documentation is confusing and it is hard to get
started with widgets and plots.
The most prominent example of this seems to be the "Bokeh tutorial".
The tutorial walks you through "*What's included*" and
"*installation*" but then it shows you "*exercises*" (?) right away,
without discussing the most important primitives or showing some
minimal working examples. I have to admit that this makes it
difficult for anyone to quickly get started with the package, and have
met at least two people who have switched to Plot.ly simply because it
is easier (faster) to get up and running with it.
While it is perfectly understandable that the documentation is
difficult to maintain given how quickly the interface is evolving, it
is, I think critical for the future of Bokeh that we put some effort
as a community in building a guide that helps people get started. This
should include a basic overview of the main modules and capabilities,
and some quick short code snippets that show useful things you can do
with Bokeh that you can't do otherwise (in my mind, these are clearly
interactive web apps)
I have tried myself to use the library several times for building
interactive visualization apps in my company, but still find the
package opaque and hard to get started with. I mean this in the
most*constructive* way possible. I *really would love* to use Bokeh at
work, and to get my team (a datascience team of 5 people) to use it
for most of the products we build, but I keep running into the same
problem: how do I build a simple app?. The only documentation I have
seen for this is in the GitHub repository (the stock GUI and others
and the videos from Peter on YouTube), and I still feel helpless when
it comes to building simple apps with the package.
As a user (and to-be-contributor) I would love to help more, but I am
afraid that, like some of my peers, I need more help in getting started.
Thanks again so much for your commitment to providing high-quality
open-source libraries. Conda is clearly a success story. Hopefully we
can replicate that with Bokeh!
Josh
--
You received this message because you are subscribed to the Google
Groups "Bokeh Discussion - Public" group.
To unsubscribe from this group and stop receiving emails from it, send
an email to [email protected]
<mailto:[email protected]>.
To post to this group, send email to [email protected]
<mailto:[email protected]>.
To view this discussion on the web visit
https://groups.google.com/a/continuum.io/d/msgid/bokeh/CAD4ivxWFrtStm7Zcdtd3CqJ%2BS_eV0Pwayj2uVAXZ_A51AU%3D1wg%40mail.gmail.com
<https://groups.google.com/a/continuum.io/d/msgid/bokeh/CAD4ivxWFrtStm7Zcdtd3CqJ%2BS_eV0Pwayj2uVAXZ_A51AU%3D1wg%40mail.gmail.com?utm_medium=email&utm_source=footer>\.
For more options, visit https://groups.google.com/a/continuum.io/d/optout\.
--
You received this message because you are subscribed to the Google Groups "Bokeh Discussion - Public" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit https://groups.google.com/a/continuum.io/d/msgid/bokeh/545D3D7A.2060007%40gmail.com\.
For more options, visit https://groups.google.com/a/continuum.io/d/optout\.
--
You received this message because you are subscribed to the Google Groups "Bokeh Discussion - Public" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit https://groups.google.com/a/continuum.io/d/msgid/bokeh/1415407278561.b3d04fb8%40Nodemailer\.
For more options, visit https://groups.google.com/a/continuum.io/d/optout\.
--
You received this message because you are subscribed to the Google Groups "Bokeh Discussion - Public" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit https://groups.google.com/a/continuum.io/d/msgid/bokeh/CADep5SKL3iMjVwB05koFui1ONrSyQ0ZaUcaKZBaUSvAorwmpMw%40mail.gmail.com\.
For more options, visit https://groups.google.com/a/continuum.io/d/optout\.