docs-bug(all): Improvement suggestion: style docs to emphasize integrity of each method #32060
Description
Documentation Feedback
Hi Angular Material Team!
This is a suggestion to improve the styling of your generated documentation -- particularly the "API" pages.
Something I've noticed over the years is that the API pages are a bit hard to read. In particular, the styling of those pages make it difficult to identify individual methods, and to understand which information to associate with which method. (Context: I just spent a fair amount of time debugging something related to flexibleDimensions on the CDKOverlay, and better/more easily intelligible docs would have definitely helped.)
My suggestion is to make simple tweaks to your styles that emphasize the boundaries between relevant units of functionality (e.g. method, class, etc), rather than using CSS borders to separate the key/label and value/description in bit of documentation about the unit of functionality.
Here's an example of what I am talking about -- the first screenshot is the page now, and the second is what happens if you give the table for each method its own background color and border, and remove the inner borders. (3 CSS property change)
All of a sudden users can actually distinguish the individual methods, and you can also see that there is no documentation for detach.
Lots more could be done with spacing, color, and typography, but this is intended as either a quick win/low-hanging fruit suggestion, or more realistically, an issue to add to your evidence pile that the docs could use some redesign with an eye towards information hierarchy in a future release.
---
Affected documentation page
all pages