Here’s a very common situation new users to a code base will find themselves in:
You want to call a function, you don’t know what it’s called, but you suspect it exists. How do you find it? Well, in code you start searching synonyms hoping one of them is contained in the function name, or the documentation.
One really good discoverability improvement you guys could make to blueprints is to also search the tooltip provided for a function, and present those options as well.
To ensure order, and prioritization of the most likely candidates you may need to use an algorithm like Term Frequency - Inverse Document Frequency to ensure the most relevant functions show up first, and weight words found in the function name.
Or alternatively provide the functions that contained the word searched in a tooltip, but not the function name in a list of “maybes” below some horizontal divide, to separate out the current list from this new “possibility” list.
We actually used to filter functions based on their comment as well, but we found this returned a lot of unhelpful functions, that crowded out the ones you actually wanted when you did know what you were looking for. I can see the value when you don’t know though. Tricky problem! We are going to allow custom ‘keywords’ for functions, though, which will let us fix issues like the one in the screenshot above. It will just take time to populate those keywords.
If we fail to find any function names containing the words you type, maybe something like you suggest where we show ‘maybe you meant this?’.
I could see it returning a lot of unhelpful functions if you were doing searching in the same manner (substring matching). Did you try using a different matching algorithm with the tooltips? For example, full word match, or “(any word) begins with…”, either of those may work a lot better at returning fewer useless options.
Yeah, if you fail to find any definitely showing the separate list of ‘maybe you meant this’ is a must have. I’m a big fan of having the tool teach the user how to use it.
You may want to begin showing those options once the list of suggestions drops to a non-zero number. Just in case the matching system finds a match that the user doesn’t care about, but can’t make go away.
Custom keywords is a solution, but I would resist pushing the data problem back onto the user to solve. If you find yourself forced down that path I would recommend augmenting the keyword system with an auto discovered keyword system. An algorithm like TF-IDF could help you auto-discover the ‘important words’ in a tooltip, and use that as a backup unless the user has provided a custom set. (note: show label with auto picked keywords). Or based on the tooltip, present the TF-IDF/other suggestions as buttons they can just click to add to the list, or type one in custom.
That’s a good point. The search algorithm has a huge impact on the quality of the results. I’m always disappointed with most apps’ help-search functionality, which is often substantially worse than just doing a Google search on the same keywords.
For now we added the ability to add keywords to functions, which will be matched in the same way as the function name. But I do think your idea of a more ‘speculative’ match for comments is cool, I’d like to investigate this later!
Maybe add in the EventGraph’s find field UI a little toggle-o-slider that lets users decide if they want to search all comments, comments matching variables or functions (or whatnot), or no comments.
Thats another interesting idea - making it easier to find the function you are looking for is clearly something we will iterate on in the future. Did you have any other examples of functions that were hard to find?
This is a question from the beta version of the engine. We are marking this answered for tracking purposes. If you are experiencing an issue similar to this please post a new question.
