The benefits of switching to a SVG icon system over a icon font system are numerous, for example:

1. Load only the icons you need
2. Faster load time because, see above
3. Smaller overall file size
4. Much crisper on high resolution displays
5. Offers even more design control
6. Predictable and performant
7. As the icons will be inlined, there are no HTTP requests

To stay consistent with the current design, the icons will still be those from the FontAwesome set, but will be inlined SVG instead of an icon font.

Bugzilla: https://bugzilla.mozilla.org/show_bug.cgi?id=1451261

Tasks

• Convert in page icons to SVG icons
• Add titles for SVG icons used a link targets
• Write Jinja helper for custom titles and l10n
• Replace remainder of icons that needs to be specified as background images in CSS
• Remove FontAwesome and all related assets.

I have been doing some reading on why one would put GA at the top of the page. The general consensus is that it is because Google said so, but there really is no good reason for it.

Worst case you loose tracking of page views where the user navigated away before the page loaded. I agree with the general feeling here that, for the performance implication, losing these "views" is not worth it.

For reference

https://github.com/h5bp/html5-boilerplate/blob/6.0.1/dist/doc/html.md#google-universal-analytics-tracking-code

h5bp/html5-boilerplate@2dfb903#commitcomment-16054505

https://mathiasbynens.be/notes/async-analytics-snippet#comment-50

I therefore propose that we move DNTHelper and the GA code to the bottom of the HTML source and mark them as async

This prevents the current blocking behaviour. Thoughts?

Original Bugzilla Ticket: https://bugzilla.mozilla.org/show_bug.cgi?id=1458197

There is still code left on Kuma that managed the display between the dev needs survey and the payments banner. Seeing that the payments banner is no longer used, the conditional code can be removed.

The dnt-helper utility almost never changes and it currently blocks rendering because of the HTTP request. It is therefore best to uglify and inline directly in the head of the document.

This is an item identified by @tkadlec as part of the performance audit

The homepage currently loads two GIF background images that could be better optimized if they were served as PNG’s.

Hero background

https://developer.mozilla.org/static/img/home-bg.ca67b4ee8675.gif

As a gif: 9.6kb
As an 8-color PNG: 2.2kb

Hero dino

https://developer.mozilla.org/static/img/home-dino.4c4029f73eb9.gif

As a gif: 26.7kb
As an 8-color PNG: 9.2kb

This involves a rethink of the entire header of MDN Web Docs including location and interaction model for breadcrumbs, search, toc, quick lang switcher, page editing tools

Concepts have been proposed here:
https://bugzilla.mozilla.org/show_bug.cgi?id=1446291

Currently, line wrapping when rendering the site allows the line to wrap between the external-link icon and the link's text. This shouldn't happen.

See the attached screenshot for an example taken from https://developer.mozilla.org/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism (it's up to you to adjust your width until it wraps).

Screenshot:

https://screenshots.firefox.com/jew3SKOddjyBUutL/developer.mozilla.org

Bugzilla: https://bugzilla.mozilla.org/show_bug.cgi?id=1391440

What is the current interaction with the following component?

It feels like this is duplicate content that is already available at the bottom of the same page. It also generally feels out of place hanging there in seemingly the middle of nowhere ;)

It also adds 13.7kb and 223ms in image load time to the overall load time of the homepage. I would vote to remove this widget if the interaction is low, and cleanup the content at the bottom of the page.

Proposal

Move it so it is side by side with the Hacks blog feed on desktop, dropping to below the feed on tablet and lower.

Mockup provided here: https://bugzilla.mozilla.org/show_bug.cgi?id=1450922

Most people simply stick GA in the header because "Google said so", but there really is no good reason for it. DNTHelper is in the header because it needs to be before we load GA.

When the one moves down, the other can move along with it.

Worst case you loose tracking of page views where the user navigated away before the page loaded. I agree with the general feeling here that, for the performance implication, losing these "views" is not worth it.

For reference

https://github.com/h5bp/html5-boilerplate/blob/6.0.1/dist/doc/html.md#google-universal-analytics-tracking-code

h5bp/html5-boilerplate@2dfb903#commitcomment-16054505

https://mathiasbynens.be/notes/async-analytics-snippet#comment-50

I therefore propose that we move DNTHelper and the GA code to the bottom of the HTML source and mark them as async

This prevents the current blocking behaviour.

Bugzilla: https://bugzilla.mozilla.org/show_bug.cgi?id=1458197

Clean up CSS

• Remove id selectors
• Remove unused CSS - Tools such as uncss, purifycss, and Chrome devtools audit can be useful here.

Cleanup general assets

• Fonts that are not part of the font stack and thus not used
• Images and SVG files not used
• Ensure all static assets are optimised at build time (NPM scripts or Webpack)

Cleanup JS

• Remove unused JS libs
• Remove dead code if any

Can this be changed to Mozilla, or to a dual copyright?

While this might not affect a large portion of our audience, it is another large dependency we no longer have to think about. This task requires a couple of individual tasks:

• Determine where jQuery UI is used on MDN Web Docs
• Determine the feasibility, of simply removing it
• If the above is not doable, how much work would it be to mimic the critical parts with CSS or vJS
• If both of the two previous tasks is not an option, then we need to create a specific bundle that includes jQuery and jQuery UI, and only load this on pages that require it.

Initially this will mostly be focused on compiling and bundling SaSS and replacing some SaSS functionality with PostCSS. As our JS codebase moves to using modern vanilla JS, Webpack can take over from plain Babeljs, to add additional tooling.

The most clearly definable benefit of this is better tooling, that leads to enhanced developer productivity. This sets up a modern workflow that allows for easier adoption of new features of the platform.

[1] https://webpack.js.org/loaders/
[2] https://webpack.js.org/loaders/sass-loader/
[3] https://webpack.js.org/loaders/postcss-loader/

Most used page of this type:
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach

Propose Yup/Nope widget design

As of January 1 2019, Mozilla requires that all GitHub projects include this CODE_OF_CONDUCT.md file in the project root. The file has two parts:

1. Required Text - All text under the headings Community Participation Guidelines and How to Report, are required, and should not be altered.
2. Optional Text - The Project Specific Etiquette heading provides a space to speak more specifically about ways people can work effectively and inclusively together. Some examples of those can be found on the Firefox Debugger project, and Common Voice. (The optional part is commented out in the raw template file, and will not be visible until you modify and uncomment that part.)

If you have any questions about this file, or Code of Conduct policies and procedures, please see Mozilla-GitHub-Standards or email [email protected].

(Message COC001)

As a precursor to using Webpack, or in tandem while the JS is being converted, we should start using Babeljs as part of our front end toolchain.

This will allow us to use modern JavaScript, take advantage of the new syntax, features, and improved performance. Because we do not have to support a wide array of old browser versions, we can use a preset-env and target a specific list of browser/version combinations[2].

This will ensure that our compiled JS is still small enough to get performance gains over and above those we will gain during parsing and execution.

[1] https://babeljs.io/
[2] https://babeljs.io/docs/plugins/preset-env/#export-with-various-targets

This is an item identified by @tkadlec as part of the performance audit

Since it’s unlikely users are hopping back and forth between different languages or locales, there doesn’t seem to be much of a caching benefit to having these fonts include full language support in one big file. Instead, can we subset these files to include on the characters necessary for each language option and load them selectively as is done already for locales with specific fonts?

The gains would be significant. For example, my estimate is that subsetting the OpenSans fonts and ZillaSlab fonts to Latin Extended would reduce font weight (currently ~350kb) by around 70% (bringing it down to ~100kb).

Add “Link to section” functionality i.e. On Github for example, when you hover over one of the top level headings in a md file an icon is revealed as below:

Even though the pages are “set-up” for this on MDN, we are not taking advantage of it. Currently, if you wish to share a link to a specific section of a piece of documentation, say the examples section of https://developer.mozilla.org/en-US/docs/Web/CSS/mask, you have to:

1. Copy the URL as above, and tell the person you are sharing with to scroll down to the Examples section or,
2. Right click on the heading and use the dev tools to get the id, you then have to add the hash to the URL manually yourself before sharing

The idea here is to make these links as on Github that will update the URL with the hash. A possible enhancement to this can be that the new URL is automatically copied to the user’s clipboard.

The link color contrast for soapbox messages is to low.

File sizes

• jQuery.js ~ 258kb (adds ~21s in download time on a 10Mbps line[excluding parsing and execution])
• It needs to be maintained as new versions are released. Our current version of jQuery suffers from a minor security vulnerability at the moment.

All functionality can be replaced with modern JavaScript that will result in an overall smaller sized codebase, and allows us to take advantage of modern JS engines, and best practices.

SVGO works amazing as a tool to optimise SVG. There is one small downside though. The output of SVGO when not passing --pretty removes the new line at the end of the file. This is not ideal because

1. Why should text files end with a newline?
   
2. What's the point in adding a new line to the end of a file?

Therefore we need to write a little Nodejs util that wraps SVO processing and adds the missing \n at the end of the file.

This is an item identified by @tkadlec as part of the performance audit

Locale-en-us.css (as well as other locales) are all tiny files (700-900 bytes) that load in whatever the fonts should be for that specific locale. Though they’re tiny, it’s still an HTTP request that has to be made which can really add up on slower connections.

Recommendations

Inline the contents of locale-*.css
Because they’re so small, inlining the contents of the locale font files makes sense provided that the files rarely change. You’re adding less than 1kb of data to each page load and saving a request for anyone without a pre-warmed cache.

There are a couple of reasons for this:

1. Our user base for these versions of Internet Explorer in incredibly low but, we still want them to be able to access the main content of the site. If we serve CSS and JS that does not work and throw tons of errors, it creates a negative user experience. We want to be sure that we do not add a maintenance headache here so, this should fallback to pretty much plain HTML with some widgets hidden with CSS.

2. We can adopt modern JavaScript, and use Babeljs to compile our JS down to a baseline. When we cut out everything less than IE11, our baseline generally has better support for modern JS. This means less down compilation. The result being a much smaller kb size for the resulting JS files.

3. Lower cost for users of low end hardware and old tech without blocking them from content.

Proposal

Serve only HTML with one simple CSS file that hides elements on the page that requires JavaScript to function.

Having analysed some data during the recent performance audit, we noticed that instead of improving performance, the preload hints are having a detrimental effect on performance.

It looks to be causing a double download, or at the very least another set of requests from within the iframe. Because the iframe is not on the same domain as MDN Web Docs, it might very well be that they are not using the same browser cache. This means the preload really has no benefit.

Also, having done a test using local overrides in Chrome dev tools, the page showed a load performance improvement of 250ms with those preload hints removed. It is therefore best to remove them.

Determine the feasibility and potential performance improvement impact of adding service workers to MDN generally, and specifically the minimally viable service worker strategy/lib - (https://adactio.com/journal/13540)

The a11y of MDN Web Docs is pretty good already, thanks in large part to the work done by @stephaniehobson. There is still room for improvement and, we need to keep in check so it does not slide.

First step is to get a lay of the land, and then also incorporate tools that will monitor this in as automated manner as possible. As a first step, we need to add Pa11y[1] to our tool chain and do an audit of key pages.

Once we have identified the biggest a11y problems that currently exist, we need to log them, prioritise and then decide an a path to resolve these.

[1] https://github.com/pa11y/
[2] mdn/kuma#4768

• [ ] Remove all CSS from the non-React Kuma codebase
• [ ] Get non-React/React Kuma landing page to display correctly
• [ ] Get non-React/React Kuma wiki page to display correctly

Bugzilla: https://bugzilla.mozilla.org/show_bug.cgi?id=1537956

What did you do?

Go to https://developer.mozilla.org/en-US/docs/Glossary

What happened?

Notice that the top border of the H2 makes a lot of vertical space, and runs into the "Learn a new term" callout.

What should have happened?

The H1 border should not cut into the callout. It would be better in general if it didn't take up so much vertical space.

Is there anything else we should know?

The problem on this particular page might be solved by adjusting the CSS of the callout. But the general issue of vertical space would not. See for example, https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/HTML_basics

The user who reported this via IRC suggested the following:

.text-content article[id=wikiArticle]>div:not([class])>h2:after, .text-content article[id=wikiArticle]>h2:after {
border-top: 3px solid #3d7e9a;
content: '';
display: block;
position: absolute;
width: 100%;}

This is currently underway in this project and can be viewed at:
https://mdn.github.io/mdn-fiori/

This will cover(not finite):

General

• Code style
• Editor configuration

CSS

• Best practise (cross pollinate with other teams on this)
• Syntax standard for both CSS and SaSS
• Documentation of linting rules we follow

JavaScript

• Best practise (cross pollinate with other teams on this)
• Syntax standard
• Documentation of linting rules we follow

HTML

• Best practise (cross pollinate with other teams on this)
• Syntax standard

Frontend Workflow

• General documentation of the front-end tool chain.

Components

Common components found in the MDN Web Docs code base with:

1. A live example of the module
2. The required HTML, CSS and JS as applicable

Tasks

• Make a back-up of the currently documented work before merging the Storybook PR
• Create issues for components
• Define typography
• Define colour scheme
• Break components down using Atomic Design principals

Bugzilla: https://bugzilla.mozilla.org/show_bug.cgi?id=1542834

@peterbe I actually didn't dare to actually print it out on paper so I used the Print to PDF on my mac. Could be that it looks different when sent to the actual HP printer.

![https://bug1542834.bmoattachments.org/attachment.cgi?id=9056645]

Bugzilla: https://bugzilla.mozilla.org/show_bug.cgi?id=1542817

Steps to reproduce

• Open dev tools Web Console
• Load https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure with Firefox Content Blocking

ReferenceError: ga is not defined

The screenshot mentioned line is referencing line 91 which isn't right but very near is the line ga('send', 'pageview', {'hitCallback': removeUtms}); which I suspect gets called after window.onload even though ga might not have been created successfully (in the lines above).

I noticed, it happens on https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach but not https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray

Clicking around, it seems quite random. Repeatable when you refresh the page but varying depending on the page.

Currently there are no unit tests for the JavaScript on MDN Web Docs. As we move to a more functional, modern, modular(all that buzz though ;)) JavaScript codebase, we need to take the opportunity to add unit tests.

This should be done in tandem with new code and rewrites. As a new piece of code lands, or a rewrite of an existing piece, it needs to be accompanied with tests.

Jest enjoys large adoption and comes with baked in support for everything we might need so, this is the suggested framework to adopt.

There are many mentions of Cupper in the repo, including in CONTRIBUTING.md. Is the conversion to an MDN project complete?

Add file type icons to search results to clearly distinguish between CSS, JS, HTML, Rust, Web Extensions etc. Makes skimming over the results much easier