Add MDN doc tooltips for tag and attribute names in the markup-view of the inspector

NEW
Unassigned

Status

()

Firefox
Developer Tools: Inspector
P3
enhancement
3 years ago
13 days ago

People

(Reporter: pbro, Unassigned, Mentored)

Tracking

Firefox Tracking Flags

(Not tracked)

Details

(Whiteboard: [devtools-ux])

Attachments

(1 attachment)

(Reporter)

Description

3 years ago
We now have MDN doc tooltips in the rule-view for CSS properties, which is awesome (bug 980006). I'm wondering if the next candidate for more MDN doc integration could be the markup-view.

We could add the same right-click context menu MDN tooltip mechanism for attribute names and tag names.
(Reporter)

Comment 1

3 years ago
@Will: could the HTML docs on MDN be used as easily as the CSS property docs?
@Jeff: does that sound like a good idea?
Depends on: 980006
(Reporter)

Updated

3 years ago
Mentor: pbrosset@mozilla.com
Created attachment 8610067 [details]
UI idea for the MDN tooltips

I can start working on this.

Step 1: The obvious stuff
- generalize the MdnDocsWidget to support not only CSS, but also HTML Tags and Atrributes. This should be quite straighforward - basically only adding more URL templates
- add the proper hooks to markup-view.js to display the tooltip
- write test cases

Step 2: Go the extra mile and improve the UI
I personally don't like much how the UI for displaying the MDN docs works now. First, the context menu is really a context menu for the whole rules inspector, containing global actions for the whole view. Suddenly, there is one new action that is rule/property specific. Second, it's a bit odd to display tooltips from a menu action - I think tooltips are a mouseover/mouseclick thing.

I know this has been already discussed in bug 980006, BUT:

Wolfram Mathematica has a way for showing docs tooltip that I think is very nice. See the attached picture. First, on mouseover, they display a tiny tooltip that contains two icons. The first one shows a summary in a tooltip bubble. The second one opens the full documentation page in a separate window. Exactly the same thing that our MDN tooltips are trying to do, right?

Opinions?
Flags: needinfo?(pbrosset)
(In reply to Patrick Brosset [:pbrosset] [:patrick] [:pbro] from comment #1)
> @Will: could the HTML docs on MDN be used as easily as the CSS property docs?
> @Jeff: does that sound like a good idea?

I think it's important to think carefully about what sort of information should be in the tooltip.

For the CSS tooltip I tried to think: what sorts of questions might developers have in mind when they're looking at a CSS property, and can we answer a fairly high proportion of them in a tooltip? If we can, great, but if we can't, it's better just to have a link direct to MDN.

For CSS I thought: people might often have questions about details of CSS property syntax, as there's a lot of it and some of it is quite complicated. For example, what are all the possible values of `justify-content`, and what do they mean? What's the order of the component parts of `animation`?

So the main content in the CSS tooltip was a commented bit of example syntax, covering all the major syntax variants. Once we decided that was what we wanted, we went back to MDN to make sure the content was correct, consistent, and discoverable. The code in the devtools was really just one bit.

(Another thing that would be very valuable would be compatibility information, but MDN isn't ready to provide that yet, but when it is we should add it.)

For the markup view, which questions do we think developers have, that we could answer in a tooltip?

It's not so obvious to me what the answer is in this case, mostly because the syntax is so much simpler. I'm not saying it's not a good idea, just to think about what to include, and be open to the possibility that just linking to the docs might be better in some cases.
(Reporter)

Comment 4

3 years ago
All good points Will. I completely agree we first need to think about what problem we're solving.

The other thing that sets the rule-view and markup-view apart is the rule-view is almost a code editor, people use to create/update styles a lot, it's almost is primary use, apart from looking at styles.
And of course, when writing code, that's when you need documentation.

The markup-view on the other hand is primarily a selection/navigation view, I think it's used a lot less as an editor (of course you can remove/add/change attributes, or even edit HTML, but I doubt this represents a large % of its use cases).

Still, there may be some cases where documentation is useful in the markup-view. What about answering these questions:

- When looking at a page I didn't create: what does this element or attribute do? (the new <picture> element with the srcset attribute is probably not very well known yet).

- What is the list of attributes that this specific element accept? (I might have added a <video> to my page, and I might not know about the poster attribute).

- What format is this attribute supposed to have already? There's a few HTML elements that accept comma-separated list of IDs for example. Or even simpler, I might be wondering if the contextmenu should be "#id" or "id", when trying to debug my contextual menu.
(Reporter)

Comment 5

2 years ago
Sorry Jarda for the really long delay answering here. Will did make a good point on comment 3, and I've been working on other things after that, hence my silence on this bug.

(In reply to Jarda Snajdr [:jsnajdr] from comment #2)
> Step 1: The obvious stuff
> - generalize the MdnDocsWidget to support not only CSS, but also HTML Tags
> and Atrributes. This should be quite straighforward - basically only adding
> more URL templates
> - add the proper hooks to markup-view.js to display the tooltip
> - write test cases
Yes, if you're still interested in working on this, I think that's a great idea. MDN pages for HTML tags and attributes might not be formatted like the ones for CSS properties, they may be less consistent and, as Will said, not all of them might be interesting to developers, nevertheless, there's no harm trying to generalize MdnDocsWidget to make it support HTML.

> Step 2: Go the extra mile and improve the UI
> I personally don't like much how the UI for displaying the MDN docs works
> now. First, the context menu is really a context menu for the whole rules
> inspector, containing global actions for the whole view. Suddenly, there is
> one new action that is rule/property specific. Second, it's a bit odd to
> display tooltips from a menu action - I think tooltips are a
> mouseover/mouseclick thing.
> 
> I know this has been already discussed in bug 980006, BUT:
> 
> Wolfram Mathematica has a way for showing docs tooltip that I think is very
> nice. See the attached picture. First, on mouseover, they display a tiny
> tooltip that contains two icons. The first one shows a summary in a tooltip
> bubble. The second one opens the full documentation page in a separate
> window. Exactly the same thing that our MDN tooltips are trying to do, right?
> 
> Opinions?
I like the idea, but I wonder if having something appear on hover wouldn't be too much in the devtools. In any case, this would need input from a UX person.
Flags: needinfo?(pbrosset)
Whiteboard: [devtools-ux]
Filter on CLIMBING SHOES
Priority: -- → P3

Updated

2 years ago
Severity: normal → enhancement
You need to log in before you can comment on or make changes to this bug.