1125803 - Implement bad/good styling for code boxes

Status: RESOLVED FIXED

(developer.mozilla.org Graveyard :: Design, enhancement)

Description

[Florian Scholz (Open Web Docs)]

What problems would this solve?
===============================
Oftentimes we present best practices along with bad examples. I propose to style the code boxes as appropriate, so that the reader clearly knows what to use and what not.

Who would use this?
===================
Readers

What would users see?
=====================
More clearly what is good code and what is bad code.

What would users do? What would happen as a result?
===================================================
A reader should be able to parse the info on the page faster as it is more obvious what the code blocks show. The reader should be more motivated to compare the bad and the good sample against each other.

Is there anything else we should know?
======================================
Inspiration: https://www.dartlang.org/articles/style-guide/

Comment 1

[Florian Scholz (Open Web Docs)]

oh, and I guess it would be nice, if the text that is displayed on the right is dynamic someone. 
So not only "bad" / "good". But maybe we want to use "old ES5 code" / "new ES6 code", for instance.

Anyway, the colors would be a really good start already :)

Comment 2

[Stephanie Hobson [:shobson]]

Attachment: Good and bad examples with colours and iconography.

What do you think of the icons being positioned over top of the first line number?

Comment 3

[Jean-Yves Perrier [:teoli]]

Comment on attachment 8560756 [details]
Good and bad examples with colours and iconography.

Looks good to me.

Edge case: what happens if highlight[1] is set on the <pre> ?

Comment 4

[Stephanie Hobson [:shobson]]

Attachment: Screen shot with line 1 highlighted.

Seems to stand up okay to having the line highlighted. The highlighting is not as pronounced but nothing looks broken.

Comment 5

[Jean-Yves Perrier [:teoli]]

It is absolutely ok, it is an edge case: we rarely want to highlight the first line anyway :-) Thx.

Comment 6

[Stephanie Hobson [:shobson]]

A first pass at this is on it's way into production. There's a page here with examples: https://developer.mozilla.org/en-US/docs/User:stephaniehobson:examples

Right now it only works on code blocks that have been processed with prism (so only works with javascript turned on) and must have headings added to the text manually by the writer. I can explore alternatives to either of these if we think it is important.

Comment 7

[Stephanie Hobson [:shobson]]

I'm going to close this since I have had only positive feedback so far :)

Comment 8

[Jean-Yves Perrier [:teoli]]

Yes! It is really nice. Well done.

Comment 9

[MDN Team (:mdn-dev)]

Commit pushed to master at https://github.com/mozilla/kuma

https://github.com/mozilla/kuma/commit/041756cb658184f5be877d252a4be272a40295ac
Bug 1125803: Good/bad code example styling

Can't rely on position:relative coming from other classes. Also can't rely on line number to be there so moved the icons to a position that doesn't rely on the line numbers being present.