Devhub update

Welcome to the official home of the WordPress Documentation Team.

This team is responsible for coordinating all documentation initiatives around WordPress, including the handbooks and other general wordsmithing across the WordPress project.

Want to get involved?

Start here to find out more about what we do and how to contribute:

Onboarding to Documentation Team: An overview of what we do and how to collaborate
Documentation Issue Tracker on GitHub: Submit any Documentation Team-related issues on GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/

Weekly meetings

Join our discussions of documentation issues here on the blog and on Slack.

The documentation team holds weekly office hours and monthly Contributor Days on each Tuesday of the month in the #docs 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/. channel. It’s also where you can contact the team at any time outside meetings.

IRC Logs

priorities
Thanks to all who attended the meeting on Tuesday. Here are our priorities/current issues:
1. Detect deprecated files. Github #11 @Rarst
2. Display source code in code reference – there’s a basic implementation of this from @atimmer 176. Waiting for @coffee2code to review and commit
3. Used by/Uses information Github #79 @Rarst. Once this is being parsed it will need to be displayed #323

Other issues

Pending the above we can implement examples #180 @coffee2code
@nicolealleyinteractivecom and @sofia-rose are working on an implementation for differentiating between different code reference entries on search results page #450. Can you please post your designs here for discussion?
a discussion needs to be had about skipping bundled libraries. @nacin thinks that bundled libraries should be skipped, @Rarst firmly thinks that they should not be. If anyone has any strong feelings either way, please leave a comment here. We’ll discuss the issue again at the next meeting.

#devhub

Drew Jaynes (DrewAPicture) 4:11 am on May 17, 2014

I agree that we should skip parsing bundled libraries — or more accurately, third-party libraries.

They don’t necessarily follow the same standards we do, and more importantly, they aren’t maintained by us so they shouldn’t live in our code reference. Seems pretty obvious to me. What are the arguments in favor of parsing them?
Andrey "Rarst" Savchenko 8:42 am on May 17, 2014

Incomplete coverage was big damn problem with Codex function reference in first place.

If I am not finding something I need to be confident it’s because it’s not there. If the data set is cut up then I have no confidence if something is not there or if reference pretends it’s not there. I need to double check with tool which gives me such confidence… Then why bother using reference in first place?

I really don’t understand the tugs (bundled, deprecated) to intentionally cripple reference coverage.
Ryan McCue 3:35 pm on May 17, 2014

I disagree with skipping bundled libraries. WordPress provides these libraries as part of its APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways., and is also ultimately responsible for backwards compatibility here too. Not including these means fragmenting the documentation and producing a less useful tool.

Likewise with not showing deprecated/internal methods. Those should be annotations on the reference page (giant flashing red banners for deprecated if needed), but not excluded from the site. They’re still useful for coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. developers (as opposed to pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party/theme developers) if internal or deprecated, and the reference should cover all of these.

The only caveat with bundled libraries is possible issues if they aren’t set to the correct @package tag, in which case that’s a bug that should be fixed.
Andrew Nacin 6:37 pm on May 20, 2014

To be clear, I don’t “think” anything or have any real opinion about this. I initially excluded bundled libraries just to speed things up during testing. Later on, I was getting tired of seeing stuff like AtomLib and Snoopy in results. (Also to be clear, no secret/private/forked code was used to do this; it’s just parsing a directory tree that has had external files manually removed.)

My supposed beliefs on this perhaps got extrapolated from my desire to avoid certain tagged items as it applies to load-scripts.php etc., but I’m not in some hypothetical “exclude all the things” camp.

We should be continuing to show deprecated and externally packaged items, but they should be treated differently, of course. Whether that means lower relevance in search results, or separated indexes, or what have you.

I would also not mind suppressing Snoopy and Magpie all together, but those are special exceptions.

Want to get involved?

Weekly meetings

Share this: