I have a thing for documentation. When I’m building something, I believe it’s my job to produce comprehensive and accessible documentation (which I actually take great pleasure in doing).
And when I’m on the other side of the equation, I surely appreciate reading and learning from it.
I consult the documentation [for a method] for the bureaucracy part of using it
Often times I know what a method is for, but I still consult the documentation for the bureaucracy part of using it:
- What parameters does it expect and in what order?
- Does it mutate any of the arguments?
- What does it return and in what format?
To make the process of finding this information as quick and easy as possible, I found that it’s important that all pages have a consistent structure I can familiarise myself with, to the point that I can just open one, scan it for a few seconds to find what I’m after and go back to what I was doing.
The MDN guidelines state that the Return value section should always be present, even if a method returns
undefined. In addition to that, it establishes other rules for consistency across pages, which I also wanted to help apply.
The process consisted of looking up each of the methods in the ECMAScript Language Specification document to find exactly what they return in all possible cases, while at the same time ensure the content and language of the new section was consistent with the existing information on the page.
Some of the methods are obsolete or simply never reached a standard implementation, which makes official information a bit more difficult to find, but I did my best to cover most of them.
This is great and all, but
… there are 443 method pages and I work a full-time job. How could I do this?
I set out to do it in a month. Got a list of all methods into a spreadsheet and established a target of 20 pages per day. This was a bit ambitious and I did miss the target massively towards the end when I just couldn’t find the extra time.
Oh, I’m not trying to paint this as a great achievement, by the way. It’s a minor improvement that will probably go unnoticed by most people, but I like to think that it will help someone at some point and that the community has an infinitesimally better resource to learn from.
If you’d like to see an improvement in a community-driven project you benefit from, offer to do it yourself. You’ll be helping other people and learning a lot in the process. I’ll make sure to keep doing that with MDN (maybe in more manageable outbursts).
Also, if you’re a developer, please don’t look at documentation as a useless, boring or even diminishing chore you have to do at the end of a project. Document often and well. It’s a good way to make sure your projects stay healthy and welcoming to new collaborators.
Finally, thanks to all the nice people on the #mdn IRC channel. Mozilla is awesome, but no real news there. ∎