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.

Optimize your site for search & social media and keep it optimized with Yoast SEO Premium

Buy this plugin now

Yoast SEO for WordPress plugin

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

Advertisements

Author: Search Engine Optimisation Company

Our team have been offering SEO expert services to clients since the early days of the internet. Whilst the tactics have evolved over the years, our overall goal by no means has and thats making sure our users web pages to rank on page 1 for appropriate keywords at the same time only using honest and long term strategies. Plan to Dominate the Search Engines? While many agencies are convinced that they have to resort to black hat SEO tactics to get results, we can get the 1st page rankings for all of our customers despite the fact that constantly guaranteeing we stick to strategies that are not frowned upon by the the search engines. What happens when you turn to black hat strategies? Without a doubt, you will get some early success, however the internet search engines will quickly discover what you are doing and you can face severe penalties which includes having your website banned with the google search results altogether. We work within guidelines of leading search engines such as Google, Yahoo and Bing! so you never need to be concerned about receiving any penalties as a result of the work we carry out for you.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s