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.

For a developer, the repository of pages that document the native primitives, structures and APIs of a given programming language are the closest thing they will ever have to an instruction manual. And it's completely wrong to think that only absolute beginners benefit from these — I've been writing JavaScript every day of my life for quite a while and I check these pages frequently.

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.

In one of my frequent visits to the Mozilla Developer Network, my go-to JavaScript instruction manual, I found that many method pages didn't have the return value clearly stated, so I would have to read through the (sometimes lengthy) document to find just that one small piece of information.

I have a huge respect for Mozilla and for what they stand for, and I knew that MDN was open to contributions from the community, so I asked around to see if I could help somehow. A few days later, there was a ticket filed in and I started reviewing every single JavaScript method page.

¶ The process

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.

¶ Conclusion

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. ∎