Examples are hard to find

[arcondello]

Github does not allow good organization of the examples. Leap has nice filtering etc but is being single sign-on. We could add to the docs? Or another front page?

[mcfarljm]

Speaking for the GitHub repositories page, the current organization methods are limited to tags as well as a default ordering made by GitHub (appears to list repositories based on most recently modified). I don't think these mechanisms are very effective for guiding users towards examples that could be of interest for them.

Regarding tags, it's not obvious to me the best way to utilize them when looking through the examples. There is a "most used topics" area that lists some tags for use in filtering, but this does not appear to list all tags. I also find the tags difficult to "trust", because it can be ambiguous whether the absence of a tag is conveying something (e.g., that a particular example does not use hybrid solution) or it was inadvertently left off (the following repos do appear to use hybrid solutions but do not include that tag: https://github.com/dwave-examples/nurse-scheduling, https://github.com/dwave-examples/hybrid-computing-notebook (!), https://github.com/dwave-examples/satellite-placement).

A different way of presenting the information that might help would be in a table. For example, like the "comparison" tables used by Wikipedia (https://en.wikipedia.org/wiki/Comparison_of_programming_languages or https://en.wikipedia.org/wiki/Comparison_of_file_comparison_tools). This makes clear the scope of information being summarized (i.e., the columns), makes it easier to maintain complete information (because it is obvious when a particular entry in the table is empty), and provides a more structured approach for things like mutually exclusive categories.

Another option, perhaps as a supplement to the more detailed table, would be to use a series of lists based on breaking out the examples into a few high-level categories. For example, graph problems, math/puzzles, machine learning, scheduling, science/engineering, etc. It would require more thought on the right organization, but would give us the opportunity to control exactly how they are presented to the user. For example, in more of a narrative fashion, "The following examples deal with graph problems:... The following deal with machine learning applications..."

In terms of implementation, perhaps the README for a pinned repository named "Comparison of examples" or "Overview of examples" could be used. Entry points such as the docs or other pages could link to this "examples overview" repository, plus it would be somewhat "discoverable" from the main page (as a pinned repo).

[randomir]

Good points, @mcfarljm.

Tags would definitely benefit from an overhaul. They were defined a year ago, and not updated much since. For now, I added hybrid-solution to the examples you listed. And we'll be adding bqm/dqm tags soon.

I'll just add, once the examples search page has been made public, we should think about providing more meaningful "related examples" (next to each example). Currently, IIRC, we simply list the next 3 examples from the search (in a way, we use query match score).

[hhtong]

@mcfarljm, I also like the idea of having an "overview" page where users can see all the examples in a series of lists that separate them into categories. I am open to the idea of having another pinned repo. Alternatively, we could add a page to the docs and link to it at the very top of dwave-examples (where ocean.dwavesys.com is currently being linked). This is less visible than a pinned repo (I had not noticed that link until now), but it'd be nice to see this list from the ocean docs side as well.

That being said, if the examples search page becomes public and we make our tagging system more consistent and clear, we could then link to that page instead. One less thing to keep up to date.

Also, currently in the docs, there is something sort of similar to the lists you're describing (though categorized by 'level'): https://docs.ocean.dwavesys.com/en/stable/getting_started.html#examples. It would be nice for this section to also include a link to whatever overview page/repo we decide on.