I cannot say this loudly or often enough: If you did not document it, it does not exist.

For two straight days, I have been trying to get to the bottom of the WTF of a few basic elements of WrdPress Themes and BuddyPress. When I say basic I really should be saying trivial or even TRIVIAL. Seriously, this was not edge-case stuff but basic newbie questions.

The problem was that despite extensive verbose documentation the basics just have not been covered. And support at BuddyPress – don’t even get me started. Oh, all right then. BuddyPress have far more support requests than they have answers with forums posts two weeks old without a single reply. My advice? Skip the official forums and use Stack Overflow and/or the Stack Exchange WordPress QnA. You are still going to have to wait a good long while for an answer but the odds of getting an answer are much higher (especially if you do your homework first).

While googling very hard for some of the answers we needed I found some amazing blogs. “Writing effective documentation for WordPress End Users” by Siobhan McKeown is one of the best posts advocating for strong documentation I have read in a long time.

Now, back to the topic of documentation. What gives guys. BuddyPress is a master stroke of much-needed WordPress functionality and clearly, has to work with a lot of guess work based coding and does so very well. I’m not going to get into the whole debate around trial and error config standards and performance. However, it seems to be working for WordPress so I’m going to give them the benefit of the doubt.

Even so, the documentation quality leaves a lot to be desired. So much so that I started to reason that it might be faster to start from scratch and document WordPress and BuddyPress by myself rather than work with what was on offer. Yeah, that’s how dissatisfied I have become. That seems to be the thinking behind queryposts.com which is third party documentation site for WordPress.

Let me say it again: If you did not document it, it does not exist.

WordPress was used by more than 27.5% of the top 10 million websites as of February 2017. So really there is no excuse for sloppy seconds in the documentation stakes. Automattic, surely you could put some of your 548 employees to work on this shortcoming?

The WordPress documentation has existed since December 2003 (that’s 14 years ago) so I could forgive some out of date content but a total lack of focus, a total lack of some of the basics… That’s just not funny. At this level of code maturity, I would expect to see detailed howto guides, recipes for common issues, and a detailed listing of internal API functions with use case examples. Even Nucleus CMS has that and they’ve been “sunset” (closed) for years (despite the community keeping right on going).

Query Posts is a step in the right direction and something that I have no doubt I will be going back to, there is still a hell of a lot of ground left not covered and therefore, does not really exist.

For example, in BuddyPress, it is probably possible to create something more like Facebook’s “pages” as well as the “groups” feature. However, as none of what you would need to know to make that happen is documented this does not exist. The code might be there, the work might be done, but the features do not exist until documented.

There is a lot that is good about WordPress and BuddyPress but documentation is not one of those things.

In the spirit of practising what we preach the team (mostly me) will be creating a series of documentation pages for Author Buzz. The aim, and it is just an aim right now, is that everything you could do with Author Buzz will be documented. The first part of that is just getting in there and using what we have so we can document it as, thanks to BuddyPress and WordPress failing to do a decent job of that, we are starting from scratch. We are writers, we should be able to do this.

Why did I think this was a good idea again?

Oh well, back to the grindstone for me.