Docs Chat Agenda – July 14, 2016

Here’s the agenda for the Docs team weekly chat, which are held Thursdays at 17:00 UTC in the #docs channel on SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/..

Current Projects Updates:

  1. Theme Developer Handbook – @kenshino
  2. Codex MigrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. (DevHub) – @drewapicture
  3. DevHub – @drewapicture
  4. HelpHub – @kenshino
  5. Inline Docs – @drewapicture

Other Stuff:

  1. Internationalizing documentation
  2. Version articles (HelpHub)
  3. Hosted about pages
  4. Open Floor

#chat, #codex-migration, #handbooks, #helphub

Codex Migration project update

History

When the docs team embarked on the Codex Migration project at the WCEU contributor dayContributor Day Contributor Days are standalone days, frequently held before or after WordCamps but they can also happen at any time. They are events where people get together to work on various areas of https://make.wordpress.org/ There are many teams that people can participate in, each with a different focus. https://2017.us.wordcamp.org/contributor-day/ https://make.wordpress.org/support/handbook/getting-started/getting-started-at-a-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 migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. 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 pingPing The act of sending a very small amount of data to an end point. Ping is used in computer science to illicit a response from a target server to test it’s connection. Ping is also a term used by Slack users to @ someone or send them a direct message (DM). Users might say something along the lines of “Ping me when the meeting starts.” me on SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. 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