In reply to Central Geek.

The core team is not of one mind and attitude. Everybody taking a step back and not making assumptions about motives would go a long way here.

I think there's a strong assumption that documentation isn't a part of everyday core development – it is. It hasn't always been, but as long as I've been the docs committer for WordPress core it has. Missing documentation wasn't always considered a bug, now it's considered vital for a commit candidate to go through. That's a huge step forward any way you look at it.

Could the shortcodes API have been more adequately documented? Sure. Could the changes that went in with 4.2.3 have been better explained? Absolutely. The balance there of course is to explain what's currently supported vs not creating a roadmap for any would-be hackers to follow, especially since this was a security release. I think we could have done a better job there all around.

Discounting the recent changes, I think it's also important to note that what we're talking about here largely falls into the category of legacy documentation – that is to say, APIs introduced long ago that were never adequately explained ... like the shortcodes or media APIs. And it's not a little bit of code we're talking about, it's literally tens of thousands of lines that have to be read, understood, and explained, sometimes without any historical context.

Call it whatever you want, "cleaning up after core developers" even, though in my experience, it's usually more productive to expend energy on lending a hand than it is on pointing out our shortcomings. I didn't write 99 percent of the code that I document, but that doesn't stop me from championing the cause.

We're all part of one community, and everyone benefits from better documentation. So when I say, "I invite you to participate" that's not a call for cleanup in aisle five, it's a acknowledgement that what we have isn't perfect, and we need the community's help to make it better.