Docs Help Make the Web Open
Daniel Appelquist
Web Developer Advocate
The web doesn’t have a marketing team. It doesn’t have a single developer program you can sign up to. And it doesn’t have a manual. That’s by design. Like the Internet, the web isn’t controlled by any single entity. But this decentralisation can also be a pain for web developers and designers.
The web has lots of documentation, but it’s often an issue for developers to find documentation that is not written from a perspective of one web product — for example, a browser or a framework. The web needs a place where people can go to get the ground truth.
Over the last decade, MDN has become that trusted source of information — a place where developers know they can get the documentation they need about how to build for the web. That’s because, even though it’s a project run by Mozilla, it documents the web across all browsers. Cross-browser compatibility is one of the key pain points of web development, and good documentation is one of the ways we can mitigate that pain. Ask any developer where they go first for documentation and they will likely cite MDN.
That’s why, in 2017, I jumped at the chance of joining the Product Advisory Board of MDN. I saw it as an opportunity to give back, and also to be a part of a project to reinforce this cross-browser message. By the way, I started my career as a technical writer, so I have opinions on the importance of good technical writing when it comes to the developer experience. The product advisory board was an experiment from MDN to bring in an external advisory group — including members from Microsoft, Google and W3C. These organisations were all already investing time in building and maintaining MDN. The PAB gave them a way to advise on product direction and hear about future planning.
Fast forward to 2020. Mozilla restructured and MDN took a hit. As a response, the same organisations (and people) who had come together to support MDN via the Product Advisory Board came together again, with others, to launch something called Open Web Docs. Open Web Docs is a new open source project, set up to help support and maintain documentation on the web — via MDN. In practice, this means that Open Web Docs will be paying writers to help write documentation and build the tools that are required to produce high-quality web documentation (for example, to maintain browser compatibility data), in collaboration with Mozilla. Open Web Docs will help to ensure the stability of MDN and will focus the activities of the multiple stakeholders in good web documentation. I’m proud to have been a part of the planning for this effort. I’m also glad that Samsung Internet will be investing our time and energy, both through our continued participation in the MDN Product Advisory Board and via Open Web Docs, in helping to document the web platform.
A beautiful library at Trinity College, Dublin. Photo by Alex Block on Unsplash
