Continuing inline docs improvements adjacent to 4.8

As we’re now into the full throes of the 4.8 cycle, the uncertainty that comes with not releasing “until it’s ready” inevitably creates a lull in areas other than the three focuses. Areas like maintaining our inline documentation, which populates the official Code Reference.

In the past, the freshness of core’s inline documentation relied almost entirely on a regular, major release schedule. And due to a preference for keeping the number of changed files low, inclusion of docs fixes in minor releases has previously been a rare occurrence.

Until now.

I’ve spoken with @matt, and the decision has been made to go ahead and prioritize some inline docs fixes for inclusion in minor releases going forward.

As with any decision, there are certainly pros and cons. Here are some of them:

Pros:

  • Ability to continue our ongoing inline docs maintenance adjacent to the 4.8 major release
  • Ability to address some glaring docs errors that we’ve been fixing manually in the Code Reference
  • Continue forward progress in documenting core JavaScript
  • Prioritize docs improvements for existing functionality in the three focus areas ahead of the 4.8 release, freeing up resources for documenting new functionality

Cons:

  • Number of changes and changed files in minor releases will increase (within reason)
  • All changes pushed to trunk will also need to be backported to the 4.7 (or current stable) branch

It’s worth noting that the reason the number of changed files has traditionally been kept low is to reduce the number of automatic update failures. The hope is that since we’ve been pushing automatic updates for 10 major versions now, reliability is less of a factor now than it has been previously.

It’s also worth noting that we shouldn’t expect a downtick in activity for core team resources focused on the three areas following this decision. As always, inline docs contributors will be focused on major release priorities before minor release ones.

This decision simply maintains the inline docs team’s ability to ensure the usefulness of core’s source documentation for the thousands of users and developers who rely on it every day.

#inline-docs, #minor-releases, #release-process

Docs-focused Bug Scrub Friday

We’ll have a docs-focused bug scrub Friday, Oct. 7 2016 14:00 CDT in the #docs Slack channel, for anyone interested in contributing. We’ll focus on the `needs-docs` keyword first, then on the `docs` focus if there’s time.

#4-7, #bug-scrub, #inline-docs

Docs Bug Scrub this Weekend

Join @morganestes in the #docs channel in Slack on Sunday, Oct. 2, 2016 3:30 p.m. CDT for a docs-focused bug scrub. We’ll plan for an hour of gardening fun. See you there!

#4-7, #bug-scrub, #inline-docs

We're discussing JS docs at this week's Inline Docs chat

For anyone interested, I’ll be hosting an Inline Docs chat this week, Wednesday 19:00 UTC in #wordpress-sfd on Freenode.

Top of the agenda is discussing options for adopting a documentation standard for core JavaScript. Anybody is welcome to attend, though we’re particularly interested in input from folks familiar with WordPress core JavaScript.

#inline-docs

Inline Docs Weekly Office Hours Time Change

Quick note to let everyone know that the Inline Docs weekly office hours time is changing.

Due to a schedule conflict, we’ll be meeting an hour later, starting this week. Same day (Wednesday), now at 20:00 UTC in #wordpress-sfd.

If you’re interested in contributing to Inline Docs, come join us!

#inline-docs

The State of Inline Docs

We haven’t posted an update in several weeks, so thought we’d bring everyone up to speed on the Inline Docs project.

This project started July at WordCamp San Francisco as a 3.7 release action item. Work continues into the 3.8 release cycle, and we would like to have the hook documentation completed by the time 3.8 is released in December.

PHP Documentation Standards

The PHP Documentation Standard has been amended several times since it was first published in early September. The latest amendments include:

If you are one of our contributors, please make sure you read the standards again to familiarize yourself with the changes.

WordCamp Contributor Days

We would like to thank WordCamp Toronto (10/6), WordCamp Europe (10/7), and WordCamp Sofia (10/27) for including Inline Docs as part of their respective Contributor Days. Approximately 35 files were documented, and several new contributors had their first patches committed to WordPress core as a result. Woot!

Contributors

So far, 47 people have received props for submitting inline docs patches:

@admiralthrawn, @aeg0125, @a.hoereth, @andg, @aralbald, @bananastalktome, @ben.moody, @betzster, @bftrick, @dllh, @drewapicture, @dougwollison, @dustyf, @enej, @ericlewis, @Faison, @FrankKlein, @gayadesign, @gizburdt, @johnafish, @johnbillion, @jonlynch, @kpdesign, @l10n, @nacin, @naomicbush, @NikV, @ninio, @miyauchi, @morduak, @Nao, @natejacobs, @netweb, @nukaga, @nullvariable, @pauldewouters, @r3df, @rzen, @sboisvert, @SergeyBiryukov, @ShinichiN, @Siobhyb, @swissspidy, @tmtoy, @tomauger, @tw2113, @vinod dalvi

There are 10 other contributors with patches waiting to be reviewed and committed that will be added to this list. We want to thank everyone for their participation so far, and hope you continue contributing!

Progress To Date

According to the “master list“, there are 185 files containing hooks to be documented. The current status, as of today:

  • Completed: 92 files (49.72%)
  • In progress: 23 files
  • Available to claim: 70 files

Weekly Office Hours

We continue to hold weekly office hours meetings on Wednesdays at 19:00 UTC in #wordpress-sfd.

#3-8, #inline-docs

Inline Docs Progress for 3.7

After last week’s weekly Inline Docs meeting we decided to begin doing a weekly ticket triage on Wednesdays.

As of last Wednesday, we’re happy to report that 19 patches have been committed to core from 12 different contributors. We’ve also updated the original make/core post to reflect the files that have been completed (please go claim some!). You can see the full report of last week’s triage on Trac. It’s really spectacular, and you should show some gratitude towards Drew for putting the report together.

Finally, beginning this week, our weekly inline-docs office hours are moving to #wordpress-sfd on Freenode. They’ll continue to be held on Wednesdays at 18:00 UTC, and we hope you can join us!

#3-7, #inline-docs

3.7 Inline Docs Weekly Office Hours

There will be a weekly office hours meeting on Wednesday, September 11, 2013 at 18:00 UTC in #wordpress-dev. Agenda includes status update on the hooks initiative that kicked off last week, and answering questions anyone may have about the effort.

If you’re interested in participating, please plan on attending.

#3-7, #inline-docs

Add Inline-Docs for Hooks

The time to document ALL THE HOOKS used throughout core is nigh.

We’ve hashed out the process in a couple of different meetings in #wordpress-dev, and we’ve added a new page to the Core Contributor Handbook that covers the broader PHPDoc standards, as well as the specific hook documentation standards (the praise for the bulk of that work should go to @kpdesign and @drewapicture, by the way).

At the bottom is a list of every file in core that has a call to either do_action() or apply_filters(). Files with a checkmark have been patched and are considered completed. Files marked with (username #xxxxx) are already claimed, and being worked on.

Directly below is the process we’re attempting to make sure each of these files can get patched swiftly with no duplicated nor wasted efforts.

How to contribute:

  1. Check the list first to make sure the file you want to work on hasn’t already been claimed.
  2. Update your local WordPress SVN or Git repo (use git pull) to the latest version of WordPress trunk (currently 3.9-alpha).
  3. Create a new ticket on Trac for the file.

    New Hook Docs Ticket Example

    • Format the title as “Hooks Docs: path/to/file.php”.
    • The Type should be “defect (bug)”.
    • Assign the ticket to the component the file is associated with.
    • Leave the Version blank.
    • Add the docs focus.
  4. Edit the file, and make a patch. Please make sure you create the patch from the root directory of your WordPress SVN or Git checkout.
  5. Upload your patch to the Trac ticket you created, and add the keyword “has-patch”.

*Note: We strongly encourage you to work on very few files at a time. In many cases, one at a time is probably best. In some cases it may make sense to tackle several at once. The important thing is that you realize your edits should be made and patched swiftly so that they aren’t invalidated by (or don’t invalidate) another patch. It’s also important to note that we’re working with a small time-table, and need to be able to claim, edit, patch quickly — which is hard to do if someone were to lay claim to 20 files at a time, and then sit on them for a few days.

Determining the since version for hooks

The recommended tool to use when searching for the version something was added to WordPress is svn blame. An additional resource for hooks is the WordPress Hooks Database. If, after using these tools, the version number cannot be determined, use @since Unknown.

Note: All @since tags should follow the three digit x.x.x format, unless it was ported from MU. Anything ported over from WPMU should use @since MU. Existing @since MU tags should not be changed.

Keeping Discussions Focused:

Any discussion about the specifics of a patch itself should happen on Trac. Any discussion about the broader scope of what we’re trying to do should take place during the weekly Inline Docs meeting on Wednesdays at 19:00 UTC in #wordpress-sfd.

Files needing patches:

Checked files are completed, marked files are claimed


Current status:

#3-7, #inline-docs

3.7 Inline Docs Office-Hours Meeting

It’s been awhile since you’ve heard from any of us about the inline-docs initiative for 3.7. We’ve been getting our ducks in a row, so to speak, and we’d like to start pounding pavement this week.

We’re going to hold an office-hours meeting on Wednesday, September 4 at 18:00 UTC in #wordpress-dev. We’ll review where we left off last meeting, cover the details on how we want to proceed, and make sure the details about getting involved really do show up here on Make/Core.

This meeting is mostly to help us on the planning team make sure we’re on the same page, but all are welcome. As I said, the next action steps for interested parties will get posted back here.

Thanks, too, for all of the encouragement around this. We’re pretty excited about it!

#3-7, #inline-docs