846515 - CSS tweaks to devhub docs

Status: RESOLVED FIXED

(Marketplace Graveyard :: Developer Pages, defect)

Description

[Fred Wenzel [:wenzel]]

From bug 844931:

- H2 and H3 elements in devhub documentation are visually identical. http://cl.ly/image/3P1o0A0Q1U1M

- Lots of whitespace (too much whitespace?) before and after <pre> elements.

- <a>s inside H* elements have no additional styling http://cl.ly/image/3Z3r342C2C0E

Comment 1

[Fred Wenzel [:wenzel]]

Tony: Who can provide the necessary CSS tweaks?

Comment 2

[Tony Santos [:tsmuse]]

I can provide the code if some one wants to make the changes, or if someone can point me in the direction of the place the CSS file(s) live I can just edit them. The H2 and H3 styling is a bug I forgot to file before our initial MWC push ended, I'm not sure about the <pre> whitespace, I'll have to look at it again, but the <a>s inside H* elements (at least in the screenshot provided) look like they're correct, because they're in the style of the menu (I'll have to double check this though).

Comment 3

[Matt Basta [:basta]]

My issue with the <a>s is that they're not visually differentiated. If I hadn't moved my mouse over them and seen the underline on hover, I never would have known that they were links.

Comment 4

[Tony Santos [:tsmuse]]

Re: H2s and H3s being the same. 
It looks like the #page article h2 and #page article h3 are sharing the same block of styles for everything including font-size and font-weight. The font-size for H2 can stay the same, let's bump the weight up to 500 or something so it looks a little more bold. Let's make the font-size for H3s 19px and leave the weight at 300.

Re: <pre> padding. 
Changing the padding to 15px all around makes all of them look a little more sane except the "git clone [e-mail]:mozilla/mortar-app-stub.git myapp" one on the app generator page, I'm not sure why that one is acting different from the rest. 

The headers that are links are acting as designed. We don't want them to look different as headers, and because they're not the only link into whatever they are linking to (the side nav has them listed as well) having them be discoverable on interaction only is what we want, instead of having a second set of headers that don't match the style of the non-link headers.

Comment 5

[Matt Basta [:basta]]

(In reply to Tony Santos [:tsmuse] from comment #4)
> The headers that are links are acting as designed. We don't want them to
> look different as headers, and because they're not the only link into
> whatever they are linking to (the side nav has them listed as well) having
> them be discoverable on interaction only is what we want, instead of having
> a second set of headers that don't match the style of the non-link headers.

By looking at the page, I wouldn't know this.

https://marketplace-dev.allizom.org/developers/docs/reference_apps

When I look at that page, I see a dumb list and have no idea how to interact with it. When I initially encountered it, I was confused. I consider myself to be a member of the target audience of the devhub, and if I'm confused, then it means that something is wrong.

Why not put a light dotted underline below the links and make it solid on hover? This would completely eliminate the confusion.

The other option is to simply remove that page and make its link in the nav simply an expander. It doesn't provide any useful information, and if (as you said yourself) it shouldn't be used for navigation, then there's no point in having it.

Comment 6

[Tony Santos [:tsmuse]]

Matt, I understand your concern but 1) one is not a trend and 2) by your previous comment, you did figure out how they worked, "If I hadn't moved my mouse over them and seen the underline on hover, I never would have known that they were links." 

They're secondary navigation, and because the primary navigation is very clear in the new side menu, creating readability issues is not a good trade off to have dueling primary navigation on a page. They're not supposed to be screamingly obvious, they're just an alternate path for the user to take advantage of if they happen to move their mouse over the body of the document. I will gladly design and run a test for this design if there is a serious concern that the secondary nav is making the site unusable, but this is a pretty standard paradigm on the web. Are you really suggesting that you wouldn't have known how to navigate to a child page via the side menu if you hadn't moved your mouse over the header? That seems a little extreme to me.

Comment 7

[Matt Basta [:basta]]

(In reply to Tony Santos [:tsmuse] from comment #6)
> Are you really suggesting that you
> wouldn't have known how to navigate to a child page via the side menu if you
> hadn't moved your mouse over the header? That seems a little extreme to me.

Having landed on the Reference Apps page from a link other than the sidebar (specifically the Reference Apps link on the "Dashboard"), yes. I did not know that there were child pages or that the headers were actually links that took you to them. I did not read the sidebar and try to parse the navigation structure of the site because I was already looking at the content.

> this is a pretty standard paradigm on the web

It's also a standard paradigm on the web to make clickable links denoted as such.

Seriously, though, why are we even having this debate? Who cares how the user ends up on the individual reference app pages as long as they do? They're developers (i.e.: power users) that are *building apps*. We can count on them to figure out how to use their back button if necessary. This is literally a one line CSS change that doesn't need to be argued about.

Comment 8

[Tony Santos [:tsmuse]]

Did the accordion menu not open to the correct position when you landed on the page from an outside link? If so, that's the issue we need to address, because that's a serious problem. 

I agree this is trivial and these users aren't new to the web, which is why I designed it this way.

Comment 9

[Matt Basta [:basta]]

(In reply to Tony Santos [:tsmuse] from comment #8)
> Did the accordion menu not open to the correct position when you landed on
> the page from an outside link? If so, that's the issue we need to address,
> because that's a serious problem. 

It opened just fine, but I wasn't focusing on the amorphous gray blob of text, I was focusing on the content central to the page that I had just clicked through to.

> I agree this is trivial and these users aren't new to the web, which is why
> I designed it this way.

I'm an engineer that's building tools for this target audience and it's was a source of confusion. The design has failed.

Comment 10

[Matt Basta [:basta]]

https://github.com/mozilla/zamboni/commit/0ed3668c444397a29a0413800d0e876ee8e47523