wbamberg

Notes from security workshop

• lots of support for a standard "Security considerations" section in reference docs, like we have for accessibility
• what are the key FE security concerns, and what is the impact? Most people are not security experts and even a basic checklist - 5 things to be careful about - would be a big step forward for most people
• security community has terms of art and some gatekeeping. Should aim to make security more accessible to people, and not act like it is someone else's problem.
• can we incorporate security advice inside IDEs and devtools
• can we have demos of security problems, to make them less abstract?
• companies don't want to invest in security, especially if their websites just work
  • if web shops are delivering to e.g. banks, then they should ask the companies to care.
• security regulation (https://en.wikipedia.org/wiki/Cyber_Resilience_Act) will make a big difference - but what exactly are the best practices going to be? We can help inform regulation here. Like

wbamberg

import bcd from "@mdn/browser-compat-data" assert { type: "json" };

const support = bcd.webextensions.api;

function checkSupport(api, browser) {
	let total = Object.keys(support[api]).length;
	let supported = 0;
	for (const feature of Object.keys(support[api])) {
		if (support[api][feature]["__compat"]) {
			if (

wbamberg

Patrick asked (I think, please lmk if I misrepresented): if we use Divio for our docs, when should stuff be in guides (explanations) and when should it be in how-tos? For instance, I'm writing as guide about offline and backgrond, and will talk about using the background fetch API, and it feels natural to include code samples for things like initiating a bg sync https://pr25305.content.dev.mdn.mozit.cloud/en-US/docs/Web/Progressive_web_apps/Guides/Offline_and_background_operation#registering_a_sync_event. But will this overlap with How-tos, and what kind of content should go in which place? I think these are good questions and I've been thinking the same thing.

I'm not going to rehash Divio here because it's better said elsewhere: https://documentation.divio.com/.

I talked this over with @Florian Scholz and this is my understanding of the conversation.

1. It's fine to have code samples inside guides. It helps break up the text and is easier for a lot of people to read than a textual description of the code

wbamberg

import sys, os

dir = sys.argv[1]

entries = os.listdir(dir)

total_interfaces = 0
total_interface_members = 0
total_overflow = 0

wbamberg

kumascript/macros/JSRef.ejs
26:var containsTag = page.hasTag;

kumascript/macros/APIRef.ejs
27:var hasTag = page.hasTag;
197:    if (hasTag(aPage, 'Experimental')) {
201:    if (hasTag(aPage, 'Non-standard') || hasTag(aPage, 'Non Standard')) {
205:    if (hasTag(aPage, 'Deprecated')) {
209:    if (hasTag(aPage, 'Obsolete')) {
228:    if (hasTag(aPage, 'Obsolete')) {

wbamberg

Interactive examples architecture and the shadow DOM

In our interactive examples architecture, examples are built as complete separate pages, served from their own domain, like this: https://interactive-examples.mdn.mozilla.net/pages/css/color.html. When we include them on MDN, we do it by creating an iframe in the MDN page, that contains the interactive examples page. So the interactive example is in its own isolated world, separate from the rest of the page.

This has some advantages. One is security: we don't have to worry much about what the example code is doing, because it can't get access to the rest of the page. So we don't really have to vet contributions much for security. Another is just isolation: if we do things in the interactive example they won't "escape" into the page. For example, in the JS interactive examples we redefine console.log() to make it write to the example's output pane, but we don't want that change to affect code running in the MDN page.

There are also some disadvantages

wbamberg

import sys, re

from os import walk, path

dir = sys.argv[1]

threshold = 20

for (dirpath, dirnames, filenames) in walk(dir):
    for filename in filenames:

wbamberg

https://developer.mozilla.org/en-us/mozilla/firefox/experimental_features : 34
https://developer.mozilla.org/en-us/web/svg/attribute : 30
https://developer.mozilla.org/en-us/web/svg/element : 42
https://developer.mozilla.org/en-us/web/guide/audio_and_video_delivery/cross-browser_audio_basics : 22
https://developer.mozilla.org/en-us/web/mathml/element : 22
https://developer.mozilla.org/en-us/web/css/css_images/using_css_gradients : 25
https://developer.mozilla.org/en-us/web/css/webkit_extensions : 30
https://developer.mozilla.org/en-us/web/css/mozilla_extensions : 36
https://developer.mozilla.org/en-us/web/css/css_columns/using_multi-column_layouts : 21
https://developer.mozilla.org/en-us/web/html/element/input/search : 21

wbamberg

files/en-us/web/api/filereader/loadend_event/index.md
37:{{page("/en-US/docs/Web/API/ProgressEvent", "Properties")}}

files/en-us/web/api/filereader/loadstart_event/index.md
37:{{page("/en-US/docs/Web/API/ProgressEvent", "Properties")}}

files/en-us/web/api/filereader/abort_event/index.md
38:{{page("/en-US/docs/Web/API/ProgressEvent", "Properties")}}

files/en-us/web/api/filereader/progress_event/index.md

wbamberg

In 2021 the Open Web Docs team, with help from Mozilla, the W3C, and the wider web docs community, converted the authoring format for MDN Web Docs - all 11,000 pages of it - from HTML to Markdown. In this post we'll talk about why we did it, how we did it, and how it turned out.

HTML soup

Before 2020 MDN was a Wiki, and contributors edited pages using a web-based WYSIWYG HTML editor. This made it easy to make casual contributions: people could edit text and apply simple formatting, like bold or code, without having to edit the underlying HTML. But a WYSIWYG editor is not well-suited to more complex edits, and authors often had to edit the underlying HTML source directly. Also, because the underlying source was hidden by default, HTML cruft, like <span id="486uw3y3"> crept into the source, often from authors pasting HTML from another rich editing environment into the MDN WYSIWYG editor.

In 2020 MDN replaced the old Wiki with a new platform in which the source for the docs was stored in a GitHub