Improving search engine results for functions

[jamen]

When I Google a specific function for Elixir looking for API docs, I am not given a link directly to that function. Instead I get a link to the module page, but this is not always obvious or useful especially if you are new to the language trying to figure out what to use.

Take a few searches as an example:

• elixir string split
• elixir binary macro
• elixir defmodule

I think if each function had their own pages, Google would index more useful information.

[josevalim]

We probably don't need to have separate pages but there is likely something we can do for Google to index the page better.

[milmazz]

We can include support for Structured Data in ExDoc with schema.org or even better with JSON-LD in the near future. wdyt?

BTW, this Structured Data Testing Tool from Google it's very handy for developers. The example shows that we don't provide any Structured Data yet :-(

[josevalim]

That's awesome @milmazz. If we can embed it directly in the markup, it definitely gets more vote.

[axelson]

I spent some time looking into this today and as far as I can tell Google does not specify how to enable a "jump_to" link in the search results. I also looked at Ruby and Go which do have "jump_to" listed (e.g. try searching for "ruby string chomp") but I do not see any structured data on the ruby page. So to me it is unclear how to accomplish this.

[davidsulc]

We generate these deep links completely algorithmically
source

It doesn't seem there's any way to configure "jump to" links for a page, only things that "increase the chances that they might appear on your pages" which are already in place in the generated documentation markup.

[matlc]

I compared the pages that come back in an Elixir search versus a couple of other languages:

No 'jump to' links:
https://www.google.com/search?q=elixir+enum+fetch

'Jump to' links:
https://www.google.com/search?q=ruby+hash+fetch
https://www.google.com/search?q=gorm+query+Count

Something we could try is how we use file-level relative links in the sidebar.

When on https://hexdocs.pm/elixir/Enum.html, the sidebar links for local anchors would be:

<a href="#fetch/2">fetch/2</a>

vs.

<a href="Enum.html#fetch/2">fetch/2</a>

I'm proposing this from the (very little) information Google puts out and comparing to the other languages' doc pages. In the link that @davidsulc provided, it talks about having the "'table of contents' which links to the individual anchors", so it seems a main mechanism that Google uses to form these links. On the Ruby and Go docs pages, each class/interface has its own page with anchor-only method lists.

I have #913 that shows the change to the sidebar links.

Let me know what you think about the idea or the code. Also, if anyone has any ideas on a safe way to trial this, I'd love to hear it.

[eksperimental]

One thing that if it will not improve search results it will still be useful is to use the full mfa in the title of every link (not only sidebar), for every module, function, type, etc.

<a href="#fetch/2" title="Enum.fetch/2">fetch/2</a>

this way it will be differentiated from other fetch/2 that may be in the same project

[eksperimental]

additionally we add the title attribute to the header of the function

<span class="signature" title="Enum.fetch/2">fetch(enumerable, index)</span>
<a href="#fetch/2" class="detail-link" title="Link to Enum.fetch/2">
  <span class="icon-link" aria-hidden="true"></span>
  <span class="sr-only">Link to Enum.fetch/2</span>
</a>

[eksperimental]

I forgot the sidebar is generated by JS code.
That is one thing that the Ruby documentation has. One thing that may help and it will not hurt and also make the project usable by people not running JS, is to have a "site map" page that links to every single module, function, type, etc. pretty much the whole sidebar expanded and converted to static HTML. It may help with the indexing.

[matlc]

I like the title suggestions @eksperimental. I'll look into adding those across all links and creating a sitemap. Those will probably be separate PRs as I can get to them. Thanks for your thoughts!

[eksperimental]

I also notice a big semantical mistake in the HTML structure,
the name of the function should be a HEADER element, <h2> to be precise.
As of now, It is just a span, and then if there is a section inside this functions, this receives h2.
We should use h2 for the function name, and them push up +1 all the headers within the function