Add a "Guides" section to the API landing page template #40427
Conversation
github-actions
bot
added
Content:Meta
|
Preview URLs (comment last updated: 2025-07-21 14:12:02) |
| For a practical usage guide with code examples, you should include a "Usage…" article in your API docs (e.g., [Using the WebVR API](/en-US/docs/Web/API/WebVR_API/Using_the_WebVR_API)). | ||
| To help improve content discoverability and {{Glossary("SEO")}}, keep the following tips in mind: | ||
| ## Guides |
There was a problem hiding this comment.
FWIW I like the idea but I don't think it makes much "difference". After all, if you're on this page you can see the guides on the sidebar.
What would actually make a difference for users is to make the sidebar work properly and include these guides in the sidebar when you aren't on a guide page.
There was a problem hiding this comment.
My checker requires every parent page to link to all its children. The main goal is to detect missing members on interface pages and other landing pages, but I think it provides value for this to be a general rule. The sidebar doesn't provide short descriptions about the page's content.
There was a problem hiding this comment.
Yes, I agree it is good - in particular there is an opportunity to talk about the content. My whine is because the guide isn't in the sidebar at all if you're not in a guide.
I have no objection to this at all. But since I wasn't assigned this is just a fly by :-)
There was a problem hiding this comment.
If you look at https://developer.mozilla.org/en-US/docs/Web/API/URL for example, the sidebar does indeed contain guides. This was added last month: mdn/rari#224
There was a problem hiding this comment.
That's awesome. Been complaining about it for years. Ignore me then.
There was a problem hiding this comment.
I'm approving. I think this is a good idea though ideally a guide should be well enough named that it would be hard to add useful extra information in just a paragraph.
Would be good to get another view - @chrisdavidmills ?
I don't agree with this change. I don't think structuring it like this is necessarily a bad idea, however, this isn't the way we've traditionally done it. The guides are clearly linked at the top of the sidebar for those who want to find them right away, and we tend to put a line at the bottom of the "Concepts and usage" section linking to the guide(s), for more information on usage. We'd have to update every page listed at https://developer.mozilla.org/en-US/docs/Web/API#specifications, for very little gain. I do love that we are now linking guides from the interface page sidebar <3 |
I already have automation to catch all such cases, so it won't be a pain. The gains OTOH:
Sure, we have some cases of doing this, but in other cases the guides are completely unlinked from the landing pages, which is the main case I'm trying to fix here. If there's already a link, then this section isn't necessary. |
OK, if we can fix these up automatically without too much hassle, I am less opposed to it.
Right. I can see how this section would be more useful in cases where there are several sequential guides. In the (numerous) cases where there is only one guide, I think it is a bit pointless. Can we include it, but mark it as optional, saying when to use it and when not to, and saying what the alternative is in the "not" cases? |
|
Of course, happy to do that. |
...s/en-us/mdn/writing_guidelines/page_structures/page_types/api_landing_page_template/index.md
Outdated
Show resolved
Hide resolved
…api_landing_page_template/index.md
|
@chrisdavidmills How does this look? |
Yup, that sounds fine. Merging! |
3 participants
Many guide pages are not reachable from their parent page, which is a minus for discoverability and for consistent IA. This adds a "Guides" section to enforce consistent structure; afterwards I can send another PR to apply this structure to API pages.