Currently, let's say you google some deno api, let's say "deno subprocess". You have a chance of ending up in any of: the Manual, or the API Reference, or examples.deno.land.
But the built-in deno.land website search only finds Manual pages in addition to modules - no way to get to the API Reference OR examples.deno.land pages from the search except find the manual page then clicking an API Reference link from there, if found.
Arguably the API reference is the most important source of information, and the search should first and foremost bring results from there - then secondarily the manual, thirdly modules, and fourthly examples.deno.land pages (if that is something we actually want examples to live in, more on that below..).
I have landed on a examples.deno.land page many times when I actually wanted to go to API Reference (through google, usually). Maybe I'm just browsing haphazardly, but I only recently noticed the tiny links to Additional resources at the end of each page, where indeed you can find the link to API Reference (which usually have examples also).
I would suggest having the additional resources on examples.deno.land pages moved to a a prominent navigation element at the top of the page, so that there is a natural continuity in jumbing between Manual, API Reference, and examples.deno.land.
It is a bit confusing and redundant that code examples may be found in any of the three different places. Not sure what should be done to that redundancy. Honestly, personally I am usually annoyed about ending up via google search or whatever on the examples.deno.land. Since actual API docs is the definite/complete source of information and more useful in that sense. Poor navigation back to the manual or API reference makes the whole site feel like a dead end.
I'm almost feeling like most of the examples should live on API docs pages, and what can't naturally find a home there, should be in the manual instead.That would remove the need for examples.deno.land completely, which would make the docs feel more consolidated and easier to search overall.
To recap, here are my suggestions for easier discussion on the concrete actionable items:
include API Reference in deno.land website-wide search.
get rid of examples.deno.land altogether, and move content to API reference where it makes sense, the rest of the content to the manual
if examples.deno.land is still thought of as usefull, various suggestion to improve the ergonomics:
3.1. also include those pages in deno.land search functionality
3.2. more prominent navigation from examples site back to manual/api reference
3.3. include deno.land website search in examples.deno.land for more natural navigation
3.4. api reference and manual should link back to examples.deno.land if the latter has better documentation/examples on the subject ("more examples over at examples.deno.land" -link)
Currently, let's say you google some deno api, let's say "deno subprocess". You have a chance of ending up in any of: the Manual, or the API Reference, or examples.deno.land.
But the built-in deno.land website search only finds Manual pages in addition to modules - no way to get to the API Reference OR examples.deno.land pages from the search except find the manual page then clicking an API Reference link from there, if found.
Arguably the API reference is the most important source of information, and the search should first and foremost bring results from there - then secondarily the manual, thirdly modules, and fourthly examples.deno.land pages (if that is something we actually want examples to live in, more on that below..).
I have landed on a examples.deno.land page many times when I actually wanted to go to API Reference (through google, usually). Maybe I'm just browsing haphazardly, but I only recently noticed the tiny links to Additional resources at the end of each page, where indeed you can find the link to API Reference (which usually have examples also).
I would suggest having the additional resources on examples.deno.land pages moved to a a prominent navigation element at the top of the page, so that there is a natural continuity in jumbing between Manual, API Reference, and examples.deno.land.
It is a bit confusing and redundant that code examples may be found in any of the three different places. Not sure what should be done to that redundancy. Honestly, personally I am usually annoyed about ending up via google search or whatever on the examples.deno.land. Since actual API docs is the definite/complete source of information and more useful in that sense. Poor navigation back to the manual or API reference makes the whole site feel like a dead end.
I'm almost feeling like most of the examples should live on API docs pages, and what can't naturally find a home there, should be in the manual instead.That would remove the need for examples.deno.land completely, which would make the docs feel more consolidated and easier to search overall.
To recap, here are my suggestions for easier discussion on the concrete actionable items: