It's difficult to find content using normal browser find

[dnfield]

More context: flutter/flutter#48924

Users would like to be able to search primarily in the current content view rather than seeing all the hits in the nav bar.

This might require something fancy but I'm sure it's possible.

/cc @mleonhard

[maceip]

how did y'all solve this? I have this issue on my flutter page

[mleonhard]

The issue title is incorrect. It should be: "Make documentation page content searchable with CTRL-F".

I just tried to search MaterialApp for the word "theme" to find constructor arguments. The search function goes through SIXTY-SEVEN instances of "theme" in the sidebar under CLASSES before it reaches the entries in the documentation part of the page.

I feel extremely frustrated every time I hit this problem. It happens multiple times a day when I'm working with Flutter.

How would you feel if you could not use CTRL-F to search in files viewed in codesearch?

The enhancement label is incorrect. This is definitely a bug.

P2 means ignore forever. I suppose it is also used for "working as intended".

Is this a subset of API Practices If You Hate Your Customers - Technique #4: Hide the API Docs from Search Engines?

[dnfield]

I really get that this is a frustrating issue. But the content is searchable via Ctrl+F, it's just tedious to do so.

As work arounds, there are other more navigable ways to consume the docs:

• In the source tree itself (ctrl/cmd click in an IDE)
• Via offline docset readers or just downloading the whole docset locally: Generate downloadable bundle of Flutter API docs flutter/flutter#9955 (comment)

I agree neither of those are solutions to this particular bug. Part of the problem, AFAICT, is that there's no easy way to do this. As a sanity check on this, MSDN docs work simiiarly, as do typical Javadoc docs, and Android's SDK documentation, etc.

Part of the problem is that this is deceptively difficult to fix. If we mess with the text in the sidebar so it's not searchable, we almost certainly will break accessibility there (and anyone that is actually trying to search in there with ctrl+f for some reason). Creating a custom find component that searches the main body first (e.g. something like what happens in Google docs when you press Ctrl+F) is probably feasible, but not trivial and would be a fairly major enhancement.

I'd be happy to be proven otherwise...

[srawlins]

P2 means ignore forever.

No that's P3 😛 . Seriously though the vast majority of bug fixes and enhancements we make here are probably P2s.

Note: we do have guidelines on how we prioritize, in the README: https://github.com/dart-lang/dartdoc/#issues-and-bugs. I think this could fit into P1 or P2. Trying to be objectionable though, I don't think the issue is widespread, meaning the "SIXTY-SEVEN instances of "theme" in the sidebar" is an outlier, not common. I'd argue "Minor display warts not significantly impeding navigation, not widespread" puts it in P2.

I was hoping there is an easy HTML / z-index 😛 trick to flip the orders, but I'm not coming up with anything. Perhaps flex order? (The site currently uses flex in layouts.)

[dnfield]

I wonder if we just want something as simple as providing some way to make the body/main content take up the full screen, so that it would be more searchable. We could even show some kind of snackbar or something suggesting the user click that button if we detect they pressed ctrl+f.

[mleonhard]

Solutions:

1. Engage a UX specialist to fix this problem. To save time, you could find a web developer who also has UX training. An added benefit is that they could fix the other usability problems with the site.
2. Move the CLASSES list to its own page. The Flutter package list contains 1,058 entries and is too big to be a regular navigation menu. Replace it with a "Related Classes" section. See "Menu Design: Checklist of 15 UX Guidelines to Help Users, Item 10 Provide local navigation menus for closely related content (Nielsen Norman Group)".
3. Put the content on the left and the CLASSES column to the right/trailing side of the page. This design choice is supported by user research.
4. Use CSS to re-arrange the order of the columns:

   <html>
   <body>
   <div style="display:flex; flex-direction:row;">
       <div style="order:2; flex-grow:1; margin-left:1em;">
           <h1>Heading1</h1>
           <p>Content1</p>
       </div>
       <div style="order:1; flex-grow:0;">
           <h1>Sidebar</h1>
           <p>Content2</p>
       </div>
   </div>
   </body>
   </html>

   

@srawlins wrote:

Trying to be objectionable though, I don't think the issue is widespread, meaning the "SIXTY-SEVEN instances of "theme" in the sidebar" is an outlier, not common. I'd argue "Minor display warts not significantly impeding navigation, not widespread" puts it in P2.

Try developing a Flutter app and see how many times you hit this problem. Searching for nearly any argument or attribute will hit the menu. It happens more with the complicated arguments, since they're the ones you will most likely need to search for.

The problem is with Flutter docs, but the fix requires a change to Dart tooling. Please do not refuse to fix this because it's not needed for "most dart packages". Don't let bureaucracy prevent your product from meeting user needs. Flutter is extremely important to Alphabet's long term profitability. When Flutter is easier to use, more app developers will use it, their Android apps will have the same quality as the iOS versions, which will boost Android's popularity, which provides user-behavior (via Analytics and Chrome) that is critical for Google's ad-matching algorithm, which makes nearly all of the company's money.

@dnfield wrote:

if we detect they pressed ctrl+f

That will surprise, confuse, and slow down users and will interfere with screen readers. You must not make documentation pages into interactive applications. Interactive elements can add functionality, but they must never be necessary. The Dart package docs provide one interactive element: the search box. It is a single-field form that shows a list of matches in a popup. But submitting the form does not show this list of matches, instead it goes to the first search result. This makes the search function less accessible and usable. So currently, the pages contain one interactive element and it harms usability. Please don't add more.

[dnfield]

Yeah, I'm fine with not adding more, but I suspec tthe UX question here is how to make docs more discoverable rather than necessarily focusing on "how do I make ctrl + F" work.

It would probably also help to find examples of HTML based docs that work well in this regard, because any major example I can think of behaves pretty much exactly like dartdoc does here (and there are examples that seem equally bad to me in terms of "the class/method list on the left has tons of words I'm looking for in the body").

[mleonhard]

Other libraries solve this problem by organizing the API into properly-named modules. The modules show the structure of the library and its important concepts. They help new users learn the API. Modules also provide important documentation for busy engineers working on existing code.

Flutter's core modules (material, cupertino, and widgets) each re-export nearly the entire Flutter API.

Flutter's poor module organization is an error that should have been fixed pre-1.0. This is the kind of thing that PMs discover and get fixed. Google gives its engineers veto power over product priorities and this means that PMs have a hard time getting anything done. One could say that Google is full of teams where every member has an extra role of product manager, for which they are untrained, unmanaged, and incentivized to perform ineffectively. For example, you engineers on this ticket are prioritizing this user-facing bug, which is product management work.

[dnfield]

@mleonhard - again, I understand this is a frustrating issue, and can appreciate that different languages have different features that may make this problem more or less serious. That said, I'd encourage you to take a look at the Dart code of conduct, which has similar expectations as the Flutter code of conduct.

Please take some time to consider those expectations, and whether you're able to continue to participate in this discussion given them.

[mleonhard]

@dnfield I apologize for the tone of my posts here. I will endeavor to be more respectful and less aggressive.