dart-lang / dartdoc

API documentation tool for Dart.
https://pub.dev/packages/dartdoc
BSD 3-Clause "New" or "Revised" License
473 stars 118 forks source link

"Implementers" section gets lost amid other parts in Dart documentation #1872

Open efortuna opened 5 years ago

efortuna commented 5 years ago

I have been getting some feedback from external users who are new to Dart (and actually... I've experienced this myself when I was first looking at Dart documentation) about how they are finding it hard to know what types implement a supertype. I've pointed out that we have that in the docs page already: (for example, "Implementers" in https://docs.flutter.io/flutter/painting/ImageProvider-class.html) but I think it is maybe not prominent enough.

Could we make this part appear higher up the page, closer to the original class name? Or at least in a bigger font? Might be worth checking in with Tao to investigate how we can best lay out all of this info so it's most discoverable.

jcollins-g commented 5 years ago

(P3 as exactly what to do isn't quantified yet). tagging @InMatrix

I've noticed this kind of thing as well, and I agree it's a problem.

As discussed offline, this seems to be a result of more docs being written, samples and videos being added, etc. so that this information -- which used to be prominent -- is now far down the page. I consider it part of navigation in some ways, which suggests it should be near the top. But I also don't want to have the opposite problem and push the actual documentation out of view.

InMatrix commented 5 years ago

Thanks for tagging. I agree with @jcollins-g's analysis. Our current page layout is getting a little difficult to accommodate the content we're adding to our API docs. We can make some short-term tweaks, for example, reducing the default height of the sample code view, or making the description of the API within a scrollable view with a smaller height. We're likely to look into dartdoc UI improvements more holistically in Q2 if not sooner.

jcollins-g commented 5 years ago

While what to do here isn't fully understood, it's well agreed that layout in general is a problem. Increasing to P2.