Documenting JavaScript in WordPress

Ever since the release of the 3.0 version of the Yoast SEO plugin, JavaScript has been a big part of it. We rely on it to make high-end features possible, like real-time content analysis. The decision to use JavaScript meant that the development team had to make a lot of choices about technologies and tools. So, we had to get a firm grasp of the use of JavaScript in WordPress.

While working on Yoast SEO 3.0, we discovered that few WordPress contributors have extensive JavaScript knowledge. At the contributors day of WordCamp Europe 2016, we saw an opportunity to help WordPress advance the future of the internet. By documenting the JavaScript in WordPress, we can make it easier for everyone to build on and enhance the code.

We believe that JavaScript is here to stay. It is a great language that helps to enrich the user experience people enjoy so much on the web. But to work towards a better JavaScript implementation and understanding of WordPress core, we had to find out what goes on!

That means documenting all the places where decisions were made, magical things happen or where complicated situations are handled. This documentation is a requirement to maintain all the functionality. It’s also crucial to prevent misunderstandings that will lead to bugs or other problems. These insights resulted in our dedication to documenting all the existing JavaScript files used in WordPress.

How we started

The first thing we did was to reserve a slot in the development calendar. Every Thursday we have two hours to work on the documentation process. This means that all developers in the office are going to work on WordPress core activities for that period of time. At the moment the primary focus is JavaScript documentation so everybody will put their time into this particular task. In the future, we might be working on other parts of the core.

To get things going, we started off with a briefing about the intentions and goals. After this meeting, we developed a practical approach. This approach consists of guidelines and tools to ensure a uniform result. Every result must follow all standards. We use these to make sure everyone works in the same way.

Tools: JSDoc

Since we’re writing JavaScript documentation, it was only logical to use JSDoc to generate a view of the state of the documentation. The WordPress standards dictate which specific tags you should use in the documentation. It’s mainly used to validate that everything is visible at the intended location.

WordPress: Coding Standards

WordPress has a precise definition on the formatting of code. This ensures that the entire code-base has the same look and feel. It helps developers in providing a unified experience throughout the platform. You all know these definitions as Coding Standards. WordPress implements separate standards for PHP and JavaScript.

There is also a precise definition on how you should format your JavaScript documentation. It is possible to use a tool to generate documentation. If you do, you can use special keywords to provide extra information about the code that is being documented.

Prioritizing files

To start, we’ve created a list of all the JavaScript files provided in a WordPress installation. From that list, we determined what files are the most complex and which ones are in the most critical places. This way, we developed a priority list.

Weekly dedication and future

Every week, all our developers have two hours to pair up and write documentation for a specific file. All patches are code reviewed internally at Yoast before we submit them to core in our attempt to make the review and merge as easy as possible. Currently, we submitted a total of five patches to the WordPress core repository. Three of them are already merged for the upcoming release 4.7.

We received very enthusiastic feedback on the patches submitted. Besides that, we had a good time (with some frustrations) figuring out what was going on. Do you want to follow our lead and get to know WordPress core better? If so, find code that doesn’t have documentation, determine what it does, write the documentation and create a patch. It is one of the most gratifying things to do and makes core documentation maintainers jump with joy!

To be continued…

We will continue to document the files until we finished them all. After that, we will evaluate how and where we’ll put our team to work. We could work on improving existing functionality, architecture and efficiency, but could also develop new features and bootstrapping core for the future.

Do you want to help? Or do you need to document your own JavaScript for a patch in WordPress core? Then you should learn all about the WordPress JavaScript documentation standard.

The merged tickets at WordPress trac:
https://core.trac.wordpress.org/ticket/37717
https://core.trac.wordpress.org/ticket/37718
https://core.trac.wordpress.org/ticket/38118
https://core.trac.wordpress.org/ticket/37365
https://core.trac.wordpress.org/ticket/37571