Conversation
| <a href="/examples/#webgl_animation_keyframes">examples (is this used? it doesn't match the new menu)</a> | ||
| </div> |
There was a problem hiding this comment.
(is this used? it doesn't match the new menu
Yes, this is used in the new documentation based on JSDoc. The file has not been updated with the new navigation (manual/docs), yet. Feel free to do that in your PR.
FYI: The new docs based on JSDoc will replace the old docs next release. We originally wanted to publish the new docs with r175. However, some additional style updates are required, see #30774 (comment). We head now for r176.
There was a problem hiding this comment.
Ah in that case yeah I need to figure out how to build and preview the JSDoc version of the site to update the PR.
I keep fumbling when navigating to the current docs:
Before:
- click on "documentation" on the home page
- start searching to lookup an API doc
- click to view (done)
Currently:
- click on "documentation" on the home page
- start typing, but then realize the API I'm looking for is not found
- realize that's because we're landing on the Manual by default now
- click over to the "docs"
- start searching again to look up an API doc
- click to view (done)
I keep doing this. I'm always wanting to go straight to the search bar to filter for API reference docs. I don't think the Manual will get this same type of usage as often.
There was a problem hiding this comment.
I think the main issue is that from the homepage there is no direct link to the API documentation. So how about the following: We provide a link "api docs" (or "api reference") that leads to the API documentation and then a second link "manual" that leads directly to the manual.
|
Closing since the suggestion didn't get enough support. Maybe it can be reconsidered if actually more users complain about the status quo. If that is not the case, it seems most users are okay with the current navigation. |
2 participants
Description
Two minor changes:
Reasoning
Concepts like "guide" and "api reference" are both are part of overall "documentation". So it seemed fit to rename "docs" (which is the api reference) to "api".
Instead of "guide" I left "manual" alone, though personally I think "guide" is more common for this thing (guide vs api reference). I also tried the word "reference" but it was a bit long, taking up too much space in the menu alongside "manual".
"guide" + "api" is my fav, but "manual" + "api" is good too, both fit under the overall concept of "documentation" (the home page link is "documentation").
screenshots
Start with the first tab after clicking "documentation" on home page:
Then go to the API section if needed (order of tabs matches the navigation):
alternative
Here's what it looks like with "reference", which happens to match the "reference" in the sidebar (we could change that to "api" too though). Possibly we could adjust the spacing if you prefer "manual" + "reference" to make it fit better:
I didn't change the folder name.
/docs/to/api/too (or/reference/if you like that more)?Where's the home page source? Some links are outdated on the home page (f.e. twitter -> x), and some links could be added (f.e. Bluesky, which is open source, and dev chatter is better and more active there).
This contribution is funded by Lume, 3D HTML framework