Learning from Mozilla: documenting the web with developer docs

You may have heard of Mozilla as the maker of the Firefox web browser. In fact, it’s so much more than this.

Mozilla campaigns to keep the internet open and free. They also make a valiant attempt to document web development with their project MDN Web Docs.

What are Mozilla web docs

There are many ‘learning to code’ resources out there, but Mozilla stands out for creating documentation aimed at beginner, intermediate and advanced web developers.

Contrary to popular belief, you can’t just ‘learn a programming language’. Languages work across platforms and alongside other languages to create applications and systems.

This creates a problem where no single organization is able (or willing) to claim ownership of ‘web development’. This results in a lack of coherent docs as developers haphazardly enter the industry. That’s why developer docs are notoriously difficult for beginners to penetrate.

It’s a badge of honor – if you’re committed enough to persevere, then you’ve earned your stripes as a developer.

In reality, bad documentation puts off potential users, and creates big problems for existing users when it’s hard for them to find the information they need. The same is true across other industries, particularly for companies who create end user product documentation.

So what can companies like these learn from Mozilla’s docs?

Comparison with Microsoft docs

By documenting ‘across’ languages, Mozilla is making a truly valuable resource that adds to their brand. This isn’t being attempted by any other organization beyond very basic code documentation.

In contrast, the Microsoft docs fall short of Mozilla’s approach by focusing exclusively on JavaScript and simply linking to ‘more information’ with regards to the other essential programming languages.

This means their docs are only useful to advanced programmers who are already well-versed in the concept of ‘web development’ and they are not accessible to beginners.

This results in their docs being simply adequate, instead of outstanding like Mozilla’s.

Mozilla’s docs are comparable end user product documentation because they are aimed at helping users to accomplish a specific task – learning web development. Product documentation has a similar goal, which is training customers to use their products.

It’s not possible to own web development since it doesn’t work in the same way as one company selling its own products. This makes MDN Web Docs a good case study, because it can highlight some common themes in how good documentation works. Companies with products to sell can learn from Mozilla.

Breakdown of MDN web docs

Mozilla doesn’t advertise its documentation on the main site because they want to avoid confusion with their official products. Once you get to their knowledge base, you can then choose between a variety of options. One of these is ‘Learn web development’.  

Their choice of topics shows how curating the content is crucial to helping your users understand the landscape of your product. Beginners don’t know the coding languages or technologies it’s possible to learn, or which ones make up the core foundation of web development.

Mozilla presents the basic topics from the outset, enabling users to gain a full picture of what they will need to learn. The ‘Information Architecture’ is providing clues to users about the topic, which benefits those with no prior experience.

Since Mozilla are not pushing an agenda (ie they’re not selling a product with their docs), this gives them the freedom to center on the user experience of their docs, and create a truly valuable learning resource. Their docs, in a sense, are their product.

They get it right by focusing on what gets their users from A to B, not what they think their users ought to know. They do this by providing several options to start with, just enough to be helpful but not so many as to be overwhelming.

Unconscious incompetence

As technical writer and blogger Tom Johnson says, “users often don’t even know what to ask. They are unaware of what they don’t know — they have unconscious incompetence. It is in this space — between unconscious competence and unconscious incompetence — that technical communicators create new knowledge that provides tremendous value.”

Using Information Architecture in this way allows users to judge that it will be worth investing the effort to use your docs, instead of spending valuable time hunting around just to find out what your docs might contain.

Mozilla’s content dives much more deeply into the various topics, such as the JavaScript programming language, but Mozilla are careful to keep this depth concealed from beginner users. At the same time, advanced users can easily find what they’re looking for through the navigation.

Encourage users to turn to your docs

It’s likely that users will be seeking out Mozilla’s web docs of their own accord, or have been recommended by a friend or colleague. The fact that users don’t have to use these docs means that using them should be a pleasurable experience and so innately motivating.

Importantly, Mozilla lets their brand’s personality come through in their documentation, which is something many companies are scared of doing. It’s a conscious departure from the robotic, clinical presentations of many other web development organizations. They do this through a combination of color scheme, fonts, engaging copy, and clean layout.

The high contrast background (white with black text and blue highlights) makes comprehension easier. The soft blue is welcoming while the fonts are plain and easy to read, as they’re large and well-laid out. Mozilla clearly explains the purpose of their docs and intentionally welcome new learners with their copy.

To make your own docs a resource that your users will voluntarily turn to, make sure you follow the Mozilla way of:

1. a) putting your users at the center of your docs
2. b) allowing your brand’s personality to shine through.

Other notes

It’s also a great example of open source documentation, as anyone can edit or add to Mozilla’s docs. By encouraging contributions from any level of developer, they also make their users feel involved in the community.

At the same time, each page is dated with the last update so you know it’s current – a crucial factor in web development. Docs can become so easily out-of-date, rendering them almost useless and wasting users’ time.

Mozilla also ranks highly for search terms like ‘javascript documentation’ which means that its docs are doing a great job of marketing themselves. Anyone searching google for programming help might easily stumble across Mozilla docs.

Other companies can aim for a similar strategy of ranking for industry keywords in search engines that link directly to their docs.

Final remarks

Web development can come across as a a closed shop to outsiders. It’s often hard for the uninitiated to get started, but Mozilla do a great job of lowering the barrier with their docs.

Their docs not only have a fantastic User Experience, but also accomplish the wider purpose of making web development more accessible to everyone.

Companies that intend to use their documentation to train customers in their product can learn from Mozilla’s approach, taking inspiration from how easy they make it for new users to get started.

From keeping their docs open source, using a friendly, casual tone, to laying the information out in a way that guides the user on their learning journey – Mozilla smashes it with their docs.

KnowledgeOwl offers dedicated knowledge base software to help you write your best support documentation. Take us for a free spin today.