API docs information architecture

angular / material.angular.io

Docs site for Angular Components

http://material.angular.io

MIT License

885 stars 395 forks source link

API docs information architecture #287

Open jelbourn opened 6 years ago

jelbourn commented 6 years ago

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 commented 6 years ago

A few more examples:

willshowell commented 6 years ago

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.
I'd also love to see breadcrumbs in the page header

Components > Navigation > Toolbar

CDK > Common Behaviors > Scrolling
cdk.angular.io 🤷‍♂️ ?
I'm a fan of the table styles for Google Maps API docs