API docs information architecture

[jelbourn]

As the library has grown, our information architecture for the API docs has become somewhat hard to navigate. Opening this issue for discussion on how we can improve it.

Questions:

• How to split up docs for classes, directives, methods, constants, functions, enums
• How to navigate between them
• How do users want to search for a specific API?

Any big change will probably include a site-wide search and cross-doc linking.

Some examples to explore:
Anything on developers.google.com
analytics.js
Android DriveApi
https://api.slack.com/methods
https://firebase.google.com/docs/reference/js/firebase.app.App

[amcdnl]

A few more examples:

• Swagger
• MDN
• MSDN

[willshowell]

1. I like how search results are organized in angular.io search. While the actual doc pages can be lacking, the realtime organization in the search banner is very nice. A downside is that there is no results page to click back to if you are disappointed in your results, but I expect that's not so much an issue compared to MDN.

2. I'd also love to see breadcrumbs in the page header

   Components > Navigation > Toolbar

   CDK > Common Behaviors > Scrolling

3. cdk.angular.io 🤷‍♂️ ?

4. I'm a fan of the table styles for Google Maps API docs