This article gives you some handy information about approaching how to document technologies.
Before starting to document or update something on MDN Web Docs, there are some things you should prepare and plan before starting to actually write.
It is assumed that before reading this guide, you have a reasonable knowledge of:
- Reading web technology specifications. You'll be looking at these a lot as you document APIs.
Everything else can be learned along the way.
Useful resources for writing any documentation include:
- The How-to guides for MDN Web Docs: You're already here, but it's good to browse through all the articles and familiarize yourself with our writing style, the different types of pages and what sections are included in them, and the different ways we include different parts of the page (like specifications and browser compatibility).
- The latest modern web browsers: These should be experimental/alpha builds such as Firefox Nightly, Chrome Canary, or Safari Technology Preview that are more likely to support the features you are documenting. This is especially pertinent if you are documenting a feature that is "upcoming".
- Demos/blog posts/other info: Find as much info as you can. If you are updating a technology because it has changed, ensure that the resources you are using to learn are not out of date. This is why the first two points above are important.
It can also be wise to try and find someone to help answer questions. This can be the specification authors or the engineers who implement browser features.
This can feel a little alien to start, but the more you do it the more you get used to it. Here are some good links to help you get started:
- How to read W3C specs by J. David Eisenberg on A List Apart
- Understanding the CSS specifications from the w3c
- How to read web specs part I – or: WebVR, how do you work? talks through reading the WebVR spec specifically, but is a great introduction to reading Web API specs.
In addition, we have the Information contained in a WebIDL file guide, which can really help when reading Web API specs.
You will return to writing code examples or building demos many times through the course of documenting a technology, but it is very useful to start by spending time familiarizing yourself with how the technology works. This is a really valuable exercise because it gives you a good understanding of what the use cases are (why a developer would use this technology) and help with creating some code examples at the same time.
Note: If the specification has been recently updated so that, say, a method is now defined differently, but the old method still works in browsers, you will often have to document both in the same place so that the old and new methods are covered. If you need help, refer to demos you have found, or ask an engineering contact.
The different pages that you need to write from scratch or update varies depending on the technology you are writing about. Check out the page types and the relevant section for the technology you're documenting. You'll most likely need to update existing documentation as well, so search MDN Web Docs for pages that are related to what you are writing about.
It's possible that the sidebar of the pages you write will also need to be defined or updated. To find out if this is needed and how to do it, check out the sidebar guide.
Some of the code examples for MDN Web Docs are held in separate repositories. Most notably, these are the interactive examples that appear in the "Try it" section in the reference pages and the larger demo code needed for guides. If you do need to add to or amend one of these repositories, it's a good idea to make a note of it in your list.
The Code examples article describes the different types of code examples we use on MDN Web Docs.
Let's say you're documenting a new Web API, your initial list of sections to be documented will look something like this:
- Overview page
- Interface pages
- Constructor pages
- Method pages
- Property pages
- Event pages
- Concept/guide pages
- Code examples
You can then expand on it with more details, adding each interface and it's members. For example, if you were documenting the Web Audio API, your list might look more like this:
- Events (update list)
It's a good idea at this point to open a tracking issue on the
mdn/content repository with the pages listed as a to-do (checkbox) list. This enables not just you, but others working on documentation to publicly keep track of the status. You can also link your pull requests to this issue to give everyone more context.