documentation icon indicating copy to clipboard operation
documentation copied to clipboard

API Reference improvements / reorganization

Open etpinard opened this issue 9 years ago • 3 comments

From @brian428 originally in https://github.com/plotly/plotly.js/issues/700

  • [x] Search!: It's really hard to find anything in the Plotly site or the API docs.
  • [x] Better top-level and sub-level navigation: Often, I'll Google for something related to Plotly.js, get a hit on the Plotly site, go look at it, and wonder "how on earth would I have gotten here without Google, using only the navigation and links on the Plotly site?" And even if you find some useful page that way, the site/page navigation gives very little indication of where you actually are in the information space.
  • [ ] Break things up: many of the really important pages take way too long to load (like https://plot.ly/javascript/, or worse, https://plot.ly/javascript/reference/). Having everything on one page makes going through the docs really slow and painful.
  • [x] In addition to site search, consider searching in the API docs themselves. Right now, I'm basically stuck using Control-F to locate anything with the current "single-monster-page" format being used

etpinard avatar Jun 28 '16 14:06 etpinard

Wasn't going to dig too far into this, but since it came up, I'll add that I've really struggled to understand the hierarchy of presentation on https://plot.ly/javascript/reference/

In particular, I wasn't totally able to make sense of the coloring of the sidebar, which I think impacted my ability to make sense of the API itself:

screen shot 2016-06-28 at 11 51 31 am

rreusser avatar Jun 28 '16 15:06 rreusser

@rreusser agreed.

And above all, we should display the attributes in order !!

plotly.js outputs the schema object in order, but out plot.ly backend load the JSON using python json.load which screws up the order. OrderedDict anyone?

etpinard avatar Jun 28 '16 16:06 etpinard

Reference is very frustrating to use. If you are at any given point on the long scroll page it's impossible to understand the context of what you're looking at.

s-nel avatar Jan 16 '17 19:01 s-nel