Documentation on using linking macros in contributing docs

[DanKaplanSES]

MDN URL

https://github.com/mdn/content/blob/main/CONTRIBUTING.md

What specific section or headline is this issue about?

No response

What information was incorrect, unhelpful, or incomplete?

I'm trying to learn about jsxref's capabilities but it's used in too many places to easily find the source of... I'm not sure what it is—is jsxref a macro?

This file is where I expected to find this information because of the other sections that already exist within it.

What did you expect to see?

I expected to find jsxref mentioned somewhere in CONTRIBUTING.md or a "Further reading" section that might lead me to learning more about jsxref or linking to documents in general.

Do you have any supporting links, references, or citations?

No response

Do you have anything more you want to share?

This is an XY Problem. What I really want to know is if jsxref can link to a document's subsection, but I've been unable to find an answer to my question because I've been unable to find jsxref's documentation and/or definition.

[wbamberg]

Most of MDN's meta-documentation is on MDN itself (I think it would be better if it were somewhere else, but it isn't) and the nearest thing to what you want is https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros#linking. The detailed docs for jsxref are in the source: https://github.com/mdn/yari/blob/main/kumascript/macros/jsxref.ejs - although tbh I hit edge cases often enough with these xref macros that the "real" documentation is the implementation!

That said it would probably be a good idea to point people at the meta-docs from CONTRIBUTING. It's really hard to find stuff in the metadocs though IMO.

[Josh-Cena]

We should DEFINITELY add more docs about jsxref. It is a really nice macro with the potential to be even better, but it's really underdocumented and people don't know how to use it properly.

[Josh-Cena]

Looking at it, I'm not sure if action is necessary. The CONTRIBUTING.md just talks about the contribution process itself, so you should first read the links at the top:

Before contributing, make sure you're familiar with the project guidelines and conventions:

• Writing guidelines - This page covers everything from how and what we write to general project guidelines.
• Writing style guide - This covers the language and style we use and how we write and format code examples.
• How to write in Markdown - This covers the Markdown features we support on MDN and custom extensions we've added.

"How to write in Markdown" mentions "KumaScript macros" at the bottom, and it should hopefully be obvious that jsxref is a macro. You will eventually arrive at https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros, where there's a link to https://github.com/mdn/yari/tree/main/kumascript/macros/jsxref.ejs.

I've thought about hosting docs for macros on MDN, but I don't think that's desirable as the macros' syntax is a moving target and documentation in comments is much easier to track.

[bsmth]

I've thought about hosting docs for macros on MDN, but I don't think that's desirable as the macros' syntax is a moving target and documentation in comments is much easier to track.

Especially at the moment, there's a lot going on with refactoring and rewrites. It might be a good idea to revisit this in a few months to audit how easy it is for authors to find information about using macros once the dust has settled.