đź“Ł Updated Documentation - Looking for feedback

Hello everyone – :wave:

After a couple years of the same look & feel, I’m excited to share that the Dash Documentation is getting a makeover! Check it out at: https://dash.plot.ly

The first changes landed tonight:

  1. The visual style has been updated to match our new look (Read more: Plotly has a new look!)

  1. We added a nice new sidebar that shows the hierarchy of pages

  2. The sidebar is filterable and we’ve put some care into it:

    1. It’s focused by default when you open up the page. So, if you want to just quickly look up the properties for e.g. dcc.Dropdown, then you can 1) open https://dash.plot.ly, 2) Starting typing immediately (no need to use your mouse or cursor), 3) Press enter to view the top result. No mouse required! It’s very fast.
    2. We’ve indexed the sidebar so that you can search all of the component properties. For example, if you are trying to find an example of the property selected_row_ids, you’ll get this result:
      image
  3. There is a persistent page menu bar on the right hand side that shows the main sections of each documentation page.

  4. In many areas, the visual style is more readable: darker fonts with higher contrast and bolded text. In particular, you’ll notice it on the reference pages that show all of the properties for a given component:

We still have lots of work to do here and we’ll update the forum with our progress. In the coming weeks, we’ll be adding:

Is there anything else that you would like to see? Please let us know by commenting below. In the meantime, I hope that you enjoy the new look & the latest features.

I hope everyone is staying safe & healthy out there :heart:

Chris

6 Likes

I’m not a huge fan of PHP, but I love their community examples section. Everytime I have needed to do something, there is an example written by a member of the community that is close enough to what I am trying to do that I can figure it out with minimal effort and usually just a few modifications.

I find Python, Pandas, and Dash to be lacking in these areas. They will often have examples, but it will only cover 10% of the use cases, and so you need to guess about the correct syntax of what you’re trying to do and hope that it’s correct. This leads you through a trial and error process that takes time, and searching stack overflow for answers which is less than ideal. The community forum here is great and very responsive, but I shouldn’t need to search it for examples of what I’m trying to do; these should exist as part of the documentation itself.

I’d really like to see a community examples section, moderated by the Dash team, at least for their API reference section. I think it would help the Dash team as well, because you would better understand how you users are using your product, which will sometimes be in ways that you wouldn’t have thought of. You can review the top-rated workaround examples and put streamlining those as features on the roadmap for future Dash versions.

2 Likes

:partying_face: Wahoo!

Love the general overhaul.

Only comment is that some of styling is a little cramped. e.g.the code sometimes bleeds in to the text around it. Perhaps a little more spacing and use of background colours to clearly separate different types of information?

1 Like

Thanks for the feedback everyone! It is very much noted.

On content updates, we just published some new chapters on callbacks (notably clientside callbacks) - Feedback welcome here: Dash Callbacks documentation improvements (including clientside examples!)

Great content! Thanks for this!

I second with the previous user’s comment that the page looks cramped. The help docs for Plotly however looks a tad cleaner. I personally am not a fan of the font family used - it seems to work fine for the Plotly homepage with little text, but not a text-dominant page- but that’s probably just me.

Plus also this line is odd:
image

The plotly docs doesn’t have this.

Selecting a dropdown from the sidebar creates this blue box:
image

Personally would prefer to entirely hide it or highlight it like how you do with the sub-headings.

Love the flexibility of the sidebar.

Love Dash overall- its fast evolving into an even greater package!

I’ve been using the new documentation a lot more, and I’ve found it much easier to find stuff! The search is really helpful, and it’s laid out well. Thanks!

1 Like

I found an issue in the new documentation. Additionally, another issue arose while trying to report the issue:

Steps to Reproduce #1

  1. Find an issue in documentation, e.g., https://dash.plotly.com/urls
  2. Look for a link or button that says edit or report errors or submit pull request

Actual Results
No such button

Expected results
A link to github where the documentation is hosted, in order to submit a pull request to fix the documentation.

Here’s the actual issue I found:

Steps to Reproduce #2

  1. Go to https://dash.plotly.com/urls
  2. Try to implement a Multi-Page app based on the “flat project layout” code examples

Actual Results
ImportError: cannot import name 'layout1' from layouts …

Expected Results
No error.

Notes:

In index.py:

from layouts import layout1, layout2
…
    if pathname == '/apps/app1':
         return layout1
…

This worked in the non-flat example, where layout1 and layout2 are files (modules). It fails in the flat example because layouts is a single file, defining layout1 and layout2 as variables.

Hello!

I know this is about dash, but there’s no dash without plotly so I figure the two are semi-synonymous. I’ve been using Dash/plotly for a couple months now, so I have the perspective of a beginner, and perhaps I could give some feedback on your documentation.

I’ve used some of your new documentation, and it’s much more helpful than your old documentation, which is why it’s so confusing why your old documentation is still up. Layout.geo in Python for example. This is really difficult to use.

You also seem to have applied the Matlab way of writing documentation, which is to say you focus on examples (which are really good) as opposed to more Numpy-style for-developers documentation. There’s a sense you’re trying to cater to the fast-and-quick but not technically advanced crowd (which is why your example documentation starts with px instead of go even though most non-official tutorials are in go) and I think that’s fine and good but it just leads to such a neglect of go/developer-oriented documentation.

It’s difficult to describe why the non-surface-level documentation is poor, but I can attempt to explain like this: when I’m using geoscatter, I want to update/specify the projection. According to your example, Scatter plots on maps in Python (“North America Precipitation Map”) this is done with fig.update_layout using a geo dict. However, update_layout’s documentation Layout in Python fails to even mention this except to note some sort of geo in “remove”. What? Why?

So the explanation goes like this: if I use other plotting software, even broken, ugly software like mpl, what is the chance that I am going to be able to figure out what I want to do with documentation (which is the way common users should code)? What is the chance that I will be able to figure out what I want to do with plotly? I would argue the second answer is “very low unless you are doing something very simple”. Basic documentation is missing and is only found in examples. Examples don’t have an exhaustive list of what your code does, because that would be extreme–having an example for every projection. However, this is a perfect example of basic documentation: just tell me what the options are. Unlike your odd, randomly named continuous color schemes–which should have a link to the names and associated color gradients every time you show a plot that uses one–all you need to do is provide a list and Wikipedia/google will do all the heavy lifting of telling me which those are.

It’s so confusing because ostensibly someone spent the time and effort to put all of these great options and functionality into your tools but then everyone forgot to tell someone you could use it. Think of the people you’ve turned away because you have to use an unspecified dict with seemingly random keys–which don’t match between px and go for some unfathomable reason and is not fully specified anywhere. This code is really weird to work with and doesn’t follow common python conventions (such as dicts! Why would you avoid IDE automatic default argument suggestion?), which pales in comparison to the beautifully interfaceable and pythonic matplotlib library (excluding 3d and more advanced features), and I honestly regret using plotly every second I do, but I am beginning to use Dash and it’s the only option. This is hurting dash adoption, even though it’s incredibly powerful (but has it’s own deep problems, thankfully not with documentation). I say this having used a variety of plotting programs for decades and having moved between a number of them without difficulty.

In short, your new documentation is much more helpful and Numpy-y, but very incomplete. Basic documentation is missing, only a portion of which is found in example webpages (which, if you want to see how that worked for Matlab, you can see the teeming forum boards with questions answered by non-employees and the general frustration by the average user). I would respectfully request full documentation be written somewhere.

1 Like

Thank you for your detailed feedback, @blondironman