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.
I’m always looking for ways to reduce barriers and create possibilities for people to be creative. Enabling people is one of the things I love doing the most.
April 25 - 26, 2024
Team Yoast is at Attending, Speaking, Sponsoring Brighton SEO! Click through to see who will be there, what we will do, and more!
See where you can find us next »
24 April 2024
Learn how to start your SEO journey the right way with our free webinar. Get practical tips and answers to all your questions in the live Q&A!
All Yoast SEO webinars »
2 Responses to Documenting JavaScript in WordPress
Elliott Porter • 8 years ago
Really enjoyed your article Jip, thank you. I will look further into the WordPress JavaScript documentation standards. I would also love to be able to set consistent time aside to contribute to WordPress, your plan has also inspired me. Look forward to keeping up with your progress on this. Thanks again.
^ Post author
Jip Moors • 8 years ago
Great to hear from you Elliott! It’s funny how such a small thing as writing documentation can still give a rush when it’s being accepted in core. Any contribution to WordPress (or any open-source project, like Yoast SEO) is greatly appreciated, especially on an important but easily overlooked part as, in this case, the old JavaScript files. Keep up the good work!
Really enjoyed your article Jip, thank you. I will look further into the WordPress JavaScript documentation standards. I would also love to be able to set consistent time aside to contribute to WordPress, your plan has also inspired me. Look forward to keeping up with your progress on this. Thanks again.
Great to hear from you Elliott! It’s funny how such a small thing as writing documentation can still give a rush when it’s being accepted in core. Any contribution to WordPress (or any open-source project, like Yoast SEO) is greatly appreciated, especially on an important but easily overlooked part as, in this case, the old JavaScript files. Keep up the good work!