Codex Migration project update

History

When the docs team embarked on the Codex Migration project at the WCEU contributor day in June 2015, it seemed like a daunting, never-ending task.

The goal was simple: move away from using the Codex as the canonical reference for developer docs to a newly-established “Developer Hub”. The bulk of the documentation would be parsed from the WordPress source and be supplemented with some manually curated documentation along with user-contributed notes (examples).

There were a lot of reasons for why the Codex migration project was launched, the most prominent being that the Codex had reach an un-maintainable state as a manually curated community reference. Now a year later, we’re well on our way toward completely migrating all function references from the Codex to the Code Reference.

Side note: The HelpHub project also falls under “Codex Migration”, but more on the user and support docs end of the spectrum. Check out the HelpHub project page for information on contributing that effort.

Examples Migration

It all started with the examples.

Over the last year, 15 or so contributors manually migrated more than 1,100 function examples to the Code Reference and submitted them to the moderation queue as user-contributed notes.

Before approval, each example was individually evaluated for accuracy, completeness, and security by about 10 trusted reviewers from throughout the community. I approved the last of the migrated examples just a few weeks ago.

Content Migration and Redirection

With mixed feedback from the community, we’ve started the long process of redirecting the more than 1,200 function references from the Codex. Like the examples, each redirection is happening manually; there’s no automation here.

Great care is being taken to ensure that any useful (and accurate) information in the Codex makes the move too, either through direct improvements to the inline docs or by being brought over to the “More Information” section of each reference page.

Side note: we’re already seeing some of the “More Information” sections getting to be pretty long in some cases, and are looking into implementing some in-page navigation to make discovery a little easier.

Thank You Contributors

At this point, I’d like to send out thanks go to all of our contributors so far: @adamsilverstein, @atachibana, @bford2here, @bhlarsen, @boogawooga, @cmmarslender, @DBrumbaugh10Up, @hearvox, @helen, @ishulev, @marcomartins, @mcadwell, @morganestes, @mrsipstenu, @ninnypants, @rabmalin, @stevegrunwell, @sudar, @theMikeD, @tott, @vlastuin, @webdevmattcrom, @znowebdev

Special thanks also go of course to @samuelsidler and @siobhan for their steadfast support in getting this project off the ground in the first place, and to @coffee2code for managing the bulk of the infrastructure, special requests, and development of features in getting us this far.

We Need Your Help

According to the progress graph, approximately 160 function references have already been migrated and redirected. There are another ~900 still to be moved. If we follow a strict regimen of migrating at least 10 references a day for the next 3 months we should be able to complete the function reference section of the Codex Migration project. Of course that still leaves class and hook references, but one thing at a time 😅

It’s doable, but I probably shouldn’t try to do it all myself without a little bit of help. If you’re reading this and thinking, “Boy, I think I can help with this,” pipe up in the comments below or ping me on Slack at @drew in the #docs channel.

We’re over the hump, but there’s a long way to go. More frequent status updates will follow.

#codex-migration, #examples