Improving the Documentation: Building a Guide and Tutorial

Josh_Wasserstein · November 7, 2014, 9:40pm

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

Hugo_Shi · November 7, 2014, 9:45pm

+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\.

Juan_Nunez-Iglesias · November 8, 2014, 12:41am

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
mostconstructive 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.

Tom_Denniston · November 8, 2014, 8:43pm

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
mostconstructive 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.

Bryan · November 9, 2014, 11:38pm

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\.

Bryan · November 10, 2014, 4:34pm

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\.

Bryan · November 10, 2014, 8:26pm

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\.

Fabio_Pliger · November 10, 2014, 9:04pm

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.

I'd be happy to help to improve documentation.. I've spent some time on it
recently and actually found it not as straightforward as I'd like.
Specially if I immagine myself just a non experienced user that "just want
to plot some data".

* 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.

That would be awesome!

* 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.

Agreed, great feature. Currently it's a bit messy to quickly find topics
around the docs.

* 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.

Now I understand why it's organized this way. My impression when going
through the tutorial was that it seemed more like a set of lessons where
you actually have the chance to interact with people and explain/ give some
context. As an user I'd expect that a tutorial just gives me the answers
for the most common use cases... with the code and link to more detailed
info/ examples.

* 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.

I think it'd be a big win for the users and the project itself and agree
with everything. One thing that needs more light is the feature list (not
only the early ones). It'd be nice to have a list of the features supported
and how to get those working with code examples... there are several cool
features that are not advertised enough. It's pity.

Cheers

Fabio

···

On Mon, Nov 10, 2014 at 9:26 PM, Bryan Van de Ven <[email protected]> wrote:

Damian_Avila · November 10, 2014, 10:42pm

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.

I agree on the devs docs, it would be useful.

* 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.

Yes, gallery needs categories... and with categories we can have some
category-based loading... right now it takes a lot of time to load all the
plots in the gallery page...

* 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.

I would be useful, but I think is low in priority compare with the other
thing detailed here.

* 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.

We certainly need to improve (redesign) the tutorial... in my experience,
people in tutorial get lost easily in the current status. I don't know the
best solution, and we probably have to discuss about that in the already
opened issues, but I think we have to change this soon, ASAP

* 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.

Yep, we need to improve that... and I think that explaining the server
concepts would be really great to help people understand all the potential
behind Bokeh...

* 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.

This would be nice, I think the big problem is where to host it and how to
get fund for that...

* "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.

Maybe "early" is a better name... I dunno... but we have to tag the thing
in some meaningful way so people can understand the current situation and
the "prone to be changed" status on theses areas. I agree on the things
that have to be considered "early".

* 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.

Yep, we have to try to embed the videos in the docs... that's probably easy
to do...

Thanks,

Bryan

Damian

···

On Mon, Nov 10, 2014 at 5:26 PM, Bryan Van de Ven <[email protected]> wrote:

Bryan · November 11, 2014, 1:16am

Yes, gallery needs categories... and with categories we can have some category-based loading... right now it takes a lot of time to load all the plots in the gallery page...

This is because full sized images got checked in for the gallery thumbs. I have reduced the size of all the gallery images drastically, but the docs have not been re-deployed yet (because we have not had a release). It should load much faster after the next deployment, even withouts splitting it up. (But we should split it up, for usability.)

I would be useful, but I think is low in priority compare with the other thing detailed here.

Really? This seems like one of the highest value ideas to me. Right now there is literally nothing that connects the user-meaningful words "linked panning" to the several gallery plats that demonstrate linked panning. Or to the tutorial exercise. Or to the reference guide section for Range. And for all the glyphs; the docs for every glyph and glyph function could (should!) link to *all* the gallery plots that use that glyph function. I think having tutorials and gallery plots show up in index and in index searches for user-meaningful terms would be an incredibly high value/low cost addition.

We certainly need to improve (redesign) the tutorial... in my experience, people in tutorial get lost easily in the current status. I don't know the best solution, and we probably have to discuss about that in the already opened issues, but I think we have to change this soon, ASAP

So I am hoping to keep to concrete proposals here as much as possible. For the tutorial my proposal is:

* add an concepts overview with a few "worked examples" that
- let people get their bearings with Bokeh
- illustrate how the exercises work
* simplify some exercises (no NumPy, etc.)

However, when you say redesign I think you have something much more drastic in mind. Can you provide concrete details of what you would change?

Yep, we have to try to embed the videos in the docs... that's probably easy to do...

Embedding videos is easy, as you say, it's producing them that will take effort.

Bryan

Bryan · November 11, 2014, 1:25am

I'd be happy to help to improve documentation.. I've spent some time on it recently and actually found it not as straightforward as I'd like. Specially if I immagine myself just a non experienced user that "just want to plot some data".

I look forward to your help! Also this "newcomer perspective" is a very valuable perspective to consider when designing docs, but of course it diminishes with experience. The first, best helpful thing you could do right now is write down/record everything you could easily, immediately find out, along with what you thought to try and do to search for it that didn't work.

Now I understand why it's organized this way. My impression when going through the tutorial was that it seemed more like a set of lessons where you actually have the chance to interact with people and explain/ give some context. As an user I'd expect that a tutorial just gives me the answers for the most common use cases... with the code and link to more detailed info/ examples.

I definitely had real exercises in mind for a tutorial. Part of that is personal bias, because that's the kind of tutorial I would want. I think that's the best way to learn. But it's clear that the tutorial needs some element of "walkthrough" as well, to help get people moving when they don't have an instructor right in front of them. So just to expand on some of my ideas for the tutorial:

* concepts overview
* worked examples (maybe to start each section)
* clearer instructions about exercises
* state explicit exercise goals before each exercise
* much more obvious links to solutions
* a "what you learned" re-cap

I think it'd be a big win for the users and the project itself and agree with everything. One thing that needs more light is the feature list (not only the early ones). It'd be nice to have a list of the features supported and how to get those working with code examples... there are several cool features that are not advertised enough. It's pity.

This is actually an obvious and fantastic, but currently completely overlooked and unimplemented idea. Just a page that rattles off Bokeh features in a little more detail than the executive summary on the landing page, that links to user guide sections and gallery examples for each of the features.

Bryan

Bryan · November 11, 2014, 1:37am

That should be: "could NOT easily, immediately find out" of course.

Bryan

···

On Nov 10, 2014, at 7:25 PM, Bryan Van de Ven <[email protected]> wrote:

I'd be happy to help to improve documentation.. I've spent some time on it recently and actually found it not as straightforward as I'd like. Specially if I immagine myself just a non experienced user that "just want to plot some data".

I look forward to your help! Also this "newcomer perspective" is a very valuable perspective to consider when designing docs, but of course it diminishes with experience. The first, best helpful thing you could do right now is write down/record everything you could easily, immediately find out, along with what you thought to try and do to search for it that didn't work.

Fabio_Pliger · November 11, 2014, 2:43pm

> I'd be happy to help to improve documentation.. I've spent some time on
it recently and actually found it not as straightforward as I'd like.
Specially if I immagine myself just a non experienced user that "just want
to plot some data".

I look forward to your help! Also this "newcomer perspective" is a very
valuable perspective to consider when designing docs, but of course it
diminishes with experience. The first, best helpful thing you could do
right now is write down/record everything you could easily, immediately
find out, along with what you thought to try and do to search for it that
didn't work.

I've spent some time on it this morning and [have to hurry] already feel my
"newcomer perspective" dimishing minute after minute..

Jokes aside, there is quite a lot to discuss about it and how should we
move with changing the docs (thinking about a new release that may be
coming next and what we'd like to include/add to that).

I'll open a GH issue (didn't find related issues to link) and PR just for
what regards this first review and leave other changes in different PRs.

> Now I understand why it's organized this way. My impression when going
through the tutorial was that it seemed more like a set of lessons where
you actually have the chance to interact with people and explain/ give some
context. As an user I'd expect that a tutorial just gives me the answers
for the most common use cases... with the code and link to more detailed
info/ examples.

I definitely had real exercises in mind for a tutorial. Part of that is
personal bias, because that's the kind of tutorial I would want. I think
that's the best way to learn. But it's clear that the tutorial needs some
element of "walkthrough" as well, to help get people moving when they don't
have an instructor right in front of them. So just to expand on some of my
ideas for the tutorial:

* concepts overview
* worked examples (maybe to start each section)
* clearer instructions about exercises
* state explicit exercise goals before each exercise
* much more obvious links to solutions
* a "what you learned" re-cap

Yes, I think you hit point. With those concepts overview and clearer
instruction about the exercises we can generate enough context for users to
understand what's happenning. Right now we just drop the code and users
need to guess what's happening from their previous experiences with similar
libraries, reading comments or by jumping to the API documentation.

···

On Tue, Nov 11, 2014 at 2:25 AM, Bryan Van de Ven <[email protected]> wrote:

Damian_Avila · November 11, 2014, 3:57pm

> Yes, gallery needs categories... and with categories we can have some
category-based loading... right now it takes a lot of time to load all the
plots in the gallery page...

This is because full sized images got checked in for the gallery thumbs. I
have reduced the size of all the gallery images drastically, but the docs
have not been re-deployed yet (because we have not had a release). It
should load much faster after the next deployment, even withouts splitting
it up. (But we should split it up, for usability.)

Great!

> I would be useful, but I think is low in priority compare with the other
thing detailed here.

Really?

yes...

This seems like one of the highest value ideas to me.

It is of high value, but high value does not necessary means high
priority... What you describe would be awesome to have, but I think the
other things has to be solved before... at last, it is a subjective matter,
because all the things here are important but some of them seems more
important depending of the people bias and needs...

Right now there is literally nothing that connects the user-meaningful
words "linked panning" to the several gallery plats that demonstrate linked
panning. Or to the tutorial exercise. Or to the reference guide section for
Range. And for all the glyphs; the docs for every glyph and glyph function
could (should!) link to *all* the gallery plots that use that glyph
function. I think having tutorials and gallery plots show up in index and
in index searches for user-meaningful terms would be an incredibly high
value/low cost addition.

> We certainly need to improve (redesign) the tutorial... in my
experience, people in tutorial get lost easily in the current status. I
don't know the best solution, and we probably have to discuss about that in
the already opened issues, but I think we have to change this soon, ASAP

So I am hoping to keep to concrete proposals here as much as possible. For
the tutorial my proposal is:

* add an concepts overview with a few "worked examples" that
- let people get their bearings with Bokeh
- illustrate how the exercises work
* simplify some exercises (no NumPy, etc.)

However, when you say redesign I think you have something much more
drastic in mind. Can you provide concrete details of what you would change?

You know that my english is a little "spanishy"... with redesign I mean
some changes and maybe some different structure...

This is my main idea:

We need to have a level-based tutorial, or different tutorial to different
public.
We could have a very basic tutorial pointed to very basic stuff and able to
be followed without help by an online user.
Then, the current tutorial would be somewhat an intermediate level tutorial
with minor changes, mostly run without errors if the user don't add
anything, and maybe make the examples more standalone, avoiding the
dependence of a previous successful run, so people got stuck can keep going
on in the tutorial flow... On this intermediate tutorial we would need to
add server based examples too, and some notebook examples.
Then a high level tutorial with more advance things (widget, embed,
animations, etc) and featuring the low level API to achieve complex
things... even we could add a section for BokehJS... or advance II
Finally, the intermediate and advance tutorial could have the current
structure which is pointed to a tutorial with an instructor help, but the
basic one has to be auto-learning...

That's my overall idea...

···

On Mon, Nov 10, 2014 at 10:16 PM, Bryan Van de Ven <[email protected]> wrote:

> Yep, we have to try to embed the videos in the docs... that's probably
easy to do...

Embedding videos is easy, as you say, it's producing them that will take
effort.

Bryan

--
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/7E0D067C-7971-452C-AEC6-6D896AEC3767%40continuum.io
.
For more options, visit https://groups.google.com/a/continuum.io/d/optout\.

Josh_Wasserstein · November 14, 2014, 12:31am

Thanks to all, and specially to the Bokeh team for:
(1) responding so quickly and offering their help to directly support early users in this thread

(2) following up quickly with this PR to improve the documentation and tutorial.

Kudos to Brian, Damian and Fabio for this. I spoke to several people, consultants and data scientists at small and big companies at the Boston Data Festival about Bokeh and, as you probably know already, there is a huge interest and excitement about this package.

Josh

···

On Tue, Nov 11, 2014 at 10:57 AM, Damian Avila [email protected] wrote:

–

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/CAM9Ly3HgaSsn61wBthB2B9qu9JTrPhMpTo_nfSAH2iJvr6ssOg%40mail.gmail.com.

For more options, visit https://groups.google.com/a/continuum.io/d/optout.

On Mon, Nov 10, 2014 at 10:16 PM, Bryan Van de Ven [email protected] wrote:

Yes, gallery needs categories… and with categories we can have some category-based loading… right now it takes a lot of time to load all the plots in the gallery page…

This is because full sized images got checked in for the gallery thumbs. I have reduced the size of all the gallery images drastically, but the docs have not been re-deployed yet (because we have not had a release). It should load much faster after the next deployment, even withouts splitting it up. (But we should split it up, for usability.)

Great!

I would be useful, but I think is low in priority compare with the other thing detailed here.

Really?

yes…

This seems like one of the highest value ideas to me.

It is of high value, but high value does not necessary means high priority… What you describe would be awesome to have, but I think the other things has to be solved before… at last, it is a subjective matter, because all the things here are important but some of them seems more important depending of the people bias and needs…

Right now there is literally nothing that connects the user-meaningful words “linked panning” to the several gallery plats that demonstrate linked panning. Or to the tutorial exercise. Or to the reference guide section for Range. And for all the glyphs; the docs for every glyph and glyph function could (should!) link to all the gallery plots that use that glyph function. I think having tutorials and gallery plots show up in index and in index searches for user-meaningful terms would be an incredibly high value/low cost addition.

We certainly need to improve (redesign) the tutorial… in my experience, people in tutorial get lost easily in the current status. I don’t know the best solution, and we probably have to discuss about that in the already opened issues, but I think we have to change this soon, ASAP

So I am hoping to keep to concrete proposals here as much as possible. For the tutorial my proposal is:

add an concepts overview with a few “worked examples” that

let people get their bearings with Bokeh

illustrate how the exercises work

simplify some exercises (no NumPy, etc.)

However, when you say redesign I think you have something much more drastic in mind. Can you provide concrete details of what you would change?

You know that my english is a little “spanishy”… with redesign I mean some changes and maybe some different structure…

This is my main idea:

We need to have a level-based tutorial, or different tutorial to different public.

We could have a very basic tutorial pointed to very basic stuff and able to be followed without help by an online user.

Then, the current tutorial would be somewhat an intermediate level tutorial with minor changes, mostly run without errors if the user don’t add anything, and maybe make the examples more standalone, avoiding the dependence of a previous successful run, so people got stuck can keep going on in the tutorial flow… On this intermediate tutorial we would need to add server based examples too, and some notebook examples.

Then a high level tutorial with more advance things (widget, embed, animations, etc) and featuring the low level API to achieve complex things… even we could add a section for BokehJS… or advance II

Finally, the intermediate and advance tutorial could have the current structure which is pointed to a tutorial with an instructor help, but the basic one has to be auto-learning…

That’s my overall idea…

Yep, we have to try to embed the videos in the docs… that’s probably easy to do…

Embedding videos is easy, as you say, it’s producing them that will take effort.

Bryan

–

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/7E0D067C-7971-452C-AEC6-6D896AEC3767%40continuum.io.
For more options, visit https://groups.google.com/a/continuum.io/d/optout.

jeanbigboute · November 15, 2014, 8:39am

Hello all. I had a very similar Bokeh experience as the original poster at almost the exact same time. I’m impressed by the capabilities, am working through the documents/tutorials, and need to know more to be able to try to solve the exercises without looking at the answers. I asked the following question in the main Anaconda group and was encouraged to ask it here as well.

Matplotlib and Matlab have a clear hierarchical structure: Canvas, figures, axes, ticks, data, labels, etc. My impression is that Bokeh has some hierarchical elements but is also more fluid in many ways - plots, glyphs, brushes, axes, tools, data sources, widgets, and the server are their own entities, interacting as needed to generate the visuals without being a strict tree-like structure. If true, this could induce me to think about my data differently. I don’t have a feel for what hooks to what, though.

Request: As the documentation catches up with the development, a simple diagram showing the relationships among the Bokeh elements would help me figure out how to plot a course through the existing documentation.

Thanks,

— JBB

Bryan · November 16, 2014, 12:19am

Jean,

Thanks for the input. There is this diagram in the Dev Guide:

http://bokeh.pydata.org/docs/dev_guide.html#low-level-object-interface

It probably ought to also be in the User Guide. Also note that it is a little out of data (there is no ObjectArrayDataSource anymore, for instance)

Bryan

···

On Nov 15, 2014, at 2:39 AM, [email protected] wrote:

Hello all. I had a very similar Bokeh experience as the original poster at almost the exact same time. I'm impressed by the capabilities, am working through the documents/tutorials, and need to know more to be able to try to solve the exercises without looking at the answers. I asked the following question in the main Anaconda group and was encouraged to ask it here as well.

Matplotlib and Matlab have a clear hierarchical structure: Canvas, figures, axes, ticks, data, labels, etc. My impression is that Bokeh has some hierarchical elements but is also more fluid in many ways - plots, glyphs, brushes, axes, tools, data sources, widgets, and the server are their own entities, interacting as needed to generate the visuals without being a strict tree-like structure. If true, this could induce me to think about my data differently. I don't have a feel for what hooks to what, though.

Request: As the documentation catches up with the development, a simple diagram showing the relationships among the Bokeh elements would help me figure out how to plot a course through the existing documentation.

Thanks,

--- JBB

--
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/4446c707-32ed-419f-b2b1-02f25f4f9e7c%40continuum.io\.
For more options, visit https://groups.google.com/a/continuum.io/d/optout\.

jeanbigboute · November 17, 2014, 1:54am

Jean,

Thanks for the input. There is this diagram in the Dev Guide:
    [http://bokeh.pydata.org/docs/dev_guide.html#low-level-object-interface](http://bokeh.pydata.org/docs/dev_guide.html#low-level-object-interface)
It probably ought to also be in the User Guide. Also note that it is a little out of data (there is no ObjectArrayDataSource anymore, for instance)

Thanks, this is very helpful.

— JBB

···

On Saturday, November 15, 2014 4:20:02 PM UTC-8, Bryan Van de ven wrote:

Bryan

On Nov 15, 2014, at 2:39 AM, [email protected] wrote:

Hello all. I had a very similar Bokeh experience as the original poster at almost the exact same time. I’m impressed by the capabilities, am working through the documents/tutorials, and need to know more to be able to try to solve the exercises without looking at the answers. I asked the following question in the main Anaconda group and was encouraged to ask it here as well.

Matplotlib and Matlab have a clear hierarchical structure: Canvas, figures, axes, ticks, data, labels, etc. My impression is that Bokeh has some hierarchical elements but is also more fluid in many ways - plots, glyphs, brushes, axes, tools, data sources, widgets, and the server are their own entities, interacting as needed to generate the visuals without being a strict tree-like structure. If true, this could induce me to think about my data differently. I don’t have a feel for what hooks to what, though.

Request: As the documentation catches up with the development, a simple diagram showing the relationships among the Bokeh elements would help me figure out how to plot a course through the existing documentation.

Thanks,

— JBB

–
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/4446c707-32ed-419f-b2b1-02f25f4f9e7c%40continuum.io.

For more options, visit https://groups.google.com/a/continuum.io/d/optout.

aschneiderman · November 20, 2014, 9:51am

Hey Bryan,

Although I don't have time (yet) to help with writing documentation, I'd be happy to give feedback on drafts; I've written a decent amount of documentation aimed at beginners. Bokeh is both so much better looking than matplotlib and potentially so much more powerful that I'd love to help make it more accessible to a wider audience.

Thanks!
Anders