Difference in how method parameters are marked

[jpmedley]

We have two different ways of marking up argument names in <dl> lists. Some pages do this:

<dt>resource</dt>

While some pages do this:

<dt><code><var>resource</var></code></dt>

For several years now, I've been under the impression that the first version was the preferred way, but I can't find any instructions that say that.

My preference is to use the first one since:

• Formatting in HTML is actually an antipattern because it usurps the role defined for CSS. More to the point, using the first method allows for global future changes with minimal effort.
• The second version is an extra burden on contributors in terms of work done on a particular PR, and it's one that will not be eliminated by the move to markdown since markdown does not have a way to do definition lists.

[Rumyra]

@wbamberg @Gregoor will this be fixed when converting to markdown?

[wbamberg]

Gregor knows this better than me but I think the converter will throw out the extra markup here and we will end up with:

`thing`

I agree with Joe that this is better.

There is more about this in #5354 .

[Gregoor]

yup, exactly what Will said. In that case <var> would be converted away and we'd end up only with an inlineCode node, i.e. thing. We could add an extra rule that turns <dt><code><var>thing</var></code></dt> as well as <dt><code><var>thing</var></code></dt> into the markdown equivalent of <dt>thing</dt>. But then again we could also do that markdown-independently

[sideshowbarker]

I’m pushing the button to convert this to a Discussion topic — since this seems more like a question to ourselves about policy/style/infrastructure.

There is more about this in #5354 .

That one also seems like something that could be converted to a Discussion topic?

Having these kinds of policy/style/infrastructure topics in the Discussions tracker rather than the Issues tracker helps to reduce the number of issues that we need to read through for triage — and also of course helps to reduce the overall Issues count — which at the moment is as 532 but was at 600+ before efforts made in the last few days got some of the open issues resolved.

Meanwhile in the Discussions tracker we currently have only 12 open discussions. So issues like this one that could benefit from the attention of the review team would seem to have a better chance at getting the attention of the review team if they’re in the Discussions tracker than they would staying here among the 500+ issues about specific content bugs and specific content-update requests.