Documentation difficult to read (dark mode)

[evmckinney9]

Feedback

Hello,

Regarding the new documentation pages, I have found that they can be somewhat difficult to read, especially in dark mode. My main issue is being able to quickly tell where one method starts and the next method begins.

Example page:

I'm no design expert but I think the pages could use more headers or colors.

Slack thread

Other comments

1. The methods don't appear in the right sidebar
2. It's not clear what scope some lines are supposed to be under, e.g. in above "Pulse scheduling method" looks like it is under Return type but maybe also is a header for the next set of methods.
3. The black highlighting on dark gray backwards is too hard to see.
4. More variations of font sizes, separator lines, indentation, etc?

[javabster]

Thanks for this feedback! We are currently investigating ways to improve the layout of the API pages and hope to be able to start making improvements soon. We're aware this is a bad UI currently so we're prioritising this work highly

[Eric-Arellano]

1, 2, and 4 should now be addressed :) Please let us know if you have further suggestions to improve things!

@gracelindsell is going to look into 3 about the highlighting of inline code.

[gracelindsell]

@Eric-Arellano for the inline code we should change the highlight from its current color (Cool Gray 100) to Cool Gray 80

[Eric-Arellano]

Thanks again, @evmckinney9, for the feedback! We've rolled out a few improvements since you opened this:

• inline code now has a border around it on dark mode, which improves contrast
• code blocks have larger font
• code blocks comments use a different color for better contrast
• the API docs were overall redesigned to use colored bars to better show where distinct methods/functions/classes/attributes are

We have two more planned improvements for API docs:

• https://github.com/Qiskit/documentation/issues/1361
• https://github.com/Qiskit/documentation/issues/1395

Please let us know if you have any other feedback or suggestions on how to make the docs more useful. Your feedback was extremely useful and prompted the first chaneg of adding a border to inline code on dark mode.