Poor Documentation is #1 Fail

The #1 reason that I will likely stop using WP as a CMS is the overall lack of any decent documentation on the NEW API. The react documentation sucks and the documentation on the WP implementation of react sucks. And I don’t think the WP docs are bad because it’s new, it’s following the same bad pattern of documentation in react and other past WP JS APIs.

I only use things that are well documented, they are the only things that last and that I can depend on.

We need more than a function name, parameters and what it returns.

I honestly do not see this changing. No JS API added to WP has ever been documented clearly. Anything dealing with JS in WP requires an exorbitant amount of time to figure out the basics and then get anything accomplished. All JS documentation for WP, from what I can see, is that the people writing the documentation assume that the people reading it have the same, or nearly the same, level of understanding as they do. They fail to see that if this were the case that these people probably wouldn’t be looking at the documentation in the first place. You understand it, so everyone else should, if they don’t then they are stupid.

I don’t see this trend changing.

Why is PHP popular? Because the documentation is stellar, anyone that has any degree of aptitude in coding can pick it up. And that documentation is still relevant for those that have been doing if for many years and have much of it memorized?

Nearly the same thing can be said about jQuery.

Why is react not popular and why are so many people complaining about its inclusion in WP. In my opinion it is hard to learn. Why is it hard to learn? Because the documentation sucks. As I said, it assumes a level of understanding that most people only get after using it for some time. Not that react is really that hard. It’s just a JS framework, not much different than jQuery. A few new concepts, but if you really understand JS then react is not much of a leap. I have been using JS in many forms since it’s introduction. Yes, I am an a certified old fart, but I’m not afraid of changing. I have been changing the way I build sites constantly for the last 30 years. I don’t need jQuery or any other framework to make JS easier for me or to deal with differences in browsers. The only reasons that I use it are 1) because it’s already in WP and available and 2) because it makes it easier for others that really don’t understand JS to pick up if they need to.

The documentation for the WP implementation of react needs to be far superior to what has been produced so far for any other JS API if they want to keep the current community involved. On the other hand, of you want to alienate most of the current community, then keep up with the same documentation pattern that we’ve seen in the past.

Another huge hurdle for many people is the assumption that in order to use react, and by extension WP, that they will need to have a new build process. That they must have understanding of and use npm, jsx, and any number of other things to get the job done. Do I need to use npm to work with react? Only if I’m using something like JSX. Do I need to use JSX? No, I don’t. As I said, react is just a JS framework and anyone that is proficient in JS can probably pick up react. How many people know this? Can these things make it easier, they might. But for those people that have knowledge of JS, using react this way would be a smaller leap and they can always add this other crap later. Most of what many people want to do are probably simple things that do not warrant a new build process in the first place.

Do I want to add a new build process? Not really. I see react as a simple tool and I can do anything with it I want without needing a new build process. Will most of the developers that now use WP make the leap to this new build process? Probably not, this is were you’re going to loose a lot of the current community. These are the people you need to write documentation for.

Not only is the API documentation poor to begin with, there is no documentation on passing anything from PHP into the API. When the page loads WP is already passing information to the page in the form of JSON. Documentation on how to hook into this process to pass additional information to the page so that it can be used needs to be expanded on greatly.