vscode-docs
vscode-docs copied to clipboard
microsoft
Improve links between Guidelines, API Reference, Guides, and more
When talking with extension authors, I've noted a recurring theme where authors feel like the extension UX guidelines, guides, and API references could be much more effective if they did a better job of pointing to each other in the docs.
Here's a relevant quote from an extension author:
Honestly, this is one of the biggest improvements that I personally feel can be made. Sometimes trying to figure out what APIs to use based on discussions/explanations in the rest of the extensions guide can be tricky. Links back from the APIs to the UX Guidelines would also be huge. There are definitely times when the API docs leave you scratching your head saying “What exactly does this do? What VSCode UI does this actually refer to?” The Messages→Notifications/Alerts is one such area of “you need to try it to figure it out” which simply slows you down.
This was partially addressed by #5366 but I think the "Links" sections in the bottom may not be discoverable enough. Nor did that work account for the API References pointing back to UX guidelines or guides.
cc @hawkticehurst @misolori
Hi @daviddossett, I can pick this up if you are not working on this already.
@muditjuneja that would be super helpful—thank you for offering! Let me know what you have in mind or feel free to just raise a PR and I'll happily review 👍
@daviddossett, Let me set the entire thing up, and then I will ask my questions.
Hi @daviddossett, I checked the notification UX guidelines page here and at the bottom, it points to a sample extension. If I understood it correctly, we should add reference to the actual API here. Many other pages have such references already. This is just one instance and I am looking for more such pages. Let me know if that is what we want.
Actually, this page already has the API references at the start but are not included in the Links section.