Skip to content
This repository has been archived by the owner on Jan 24, 2024. It is now read-only.

Remove title attributes from xref macros #2787

Closed
Elchi3 opened this issue Feb 6, 2020 · 5 comments
Closed

Remove title attributes from xref macros #2787

Elchi3 opened this issue Feb 6, 2020 · 5 comments
Assignees
Labels
Cf:High Confidence: High Est:Medium Task estimated as medium (up to a day's work?)

Comments

@Elchi3
Copy link
Member

Elchi3 commented Feb 6, 2020

User story

As an MDN maintainer, I want to convert MDN JavaScript docs from HTML to markdown, so I can edit documentation effectively once MDN content is stored on GitHub. The title attributes currently contain the page's summary in the rendered html. If we stop to do this, it will allow us to generate cleaner markdown.

Acceptance criteria

xref macros that are used in the JS docs can be rendered out without title attributes.

Current output of e.g. {{jsxref("Array")}}:

<a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array"
     title="The JavaScript Array class is a global object that is used in the
     construction of arrays; which are high-level, list-like objects.">
<code>Array</code>
</a>

Which would create noisy markdown and duplicate the page summary into articles where we don't want to maintain the page summary again:

[`Array`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array 
"The JavaScript Array class is a global object that is used in the
     construction of arrays; which are high-level, list-like objects.")

Desired output of {{jsxref("Array")}}:

<a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">
  <code>Array</code>
</a>

which would generate a clean markdown like this:

[`Array`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)

It is assumed that links lacking a title containing the page summary has no effect on SEO. Or in other words: title attributes on links never had benefits in the first place (ping @atopal).
For accessibility, it also seems to rather hurt that we are having noisy titles.

Tasks

@Elchi3 Elchi3 added Cf:High Confidence: High macro Est:Medium Task estimated as medium (up to a day's work?) labels Feb 6, 2020
@Elchi3 Elchi3 added this to the Alfa-Bravo (Q1 2020) milestone Feb 6, 2020
@Elchi3 Elchi3 self-assigned this Feb 6, 2020
@a2sheppy
Copy link
Contributor

a2sheppy commented Feb 6, 2020

I don't think "cleaner markdown" is a good reason to remove functionality, unless we follow up by adding code to the platform to generate the tooltips automatically on the fly. These are incredibly useful and I don't think we should lose this feature.

Keep in mind how thrilled we were when Microsoft added tooltips presenting data from MDN into VS Code. You're proposing removing this from MDN even though we acknowledge it's a useful feature.

I use them instead of actually visiting pages a few times a day most days, if all I need is a quick reminder what something is. Not just on MDN, but on other sites that do the same thing.

@Elchi3
Copy link
Member Author

Elchi3 commented Feb 6, 2020

Keep in mind how thrilled we were when Microsoft added tooltips presenting data from MDN into VS Code.

This has nothing to do with VS Code.

You're proposing removing this from MDN even though we acknowledge it's a useful feature.

I've not acknowledged them as useful. I said they have no effect on SEO, they are even bad for accessibility, and they are bad for our conversion to markdown.

@Elchi3
Copy link
Member Author

Elchi3 commented Feb 20, 2020

The title attributes have been removed from all 4 macros. I think the next step is to render them out. @wbamberg, do we do that here or in https://github.com/mdn/sprints/issues/2522?

@wbamberg
Copy link

I think we should do that in https://github.com/mdn/sprints/issues/2522, and close this one :).

@Elchi3
Copy link
Member Author

Elchi3 commented Feb 21, 2020

Okay, closing here then.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Cf:High Confidence: High Est:Medium Task estimated as medium (up to a day's work?)
Projects
None yet
Development

No branches or pull requests

3 participants