Title: Poor Documentation is #1 Fail
Last modified: January 9, 2019

---

# Poor Documentation is #1 Fail

 *  [John Huebner](https://wordpress.org/support/users/hube2/)
 * (@hube2)
 * [7 years, 7 months ago](https://wordpress.org/support/topic/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.

The topic ‘Poor Documentation is #1 Fail’ is closed to new replies.

 * ![](https://ps.w.org/gutenberg/assets/icon-256x256.jpg?rev=1776042)
 * [Gutenberg](https://wordpress.org/plugins/gutenberg/)
 * [Frequently Asked Questions](https://wordpress.org/plugins/gutenberg/#faq)
 * [Support Threads](https://wordpress.org/support/plugin/gutenberg/)
 * [Active Topics](https://wordpress.org/support/plugin/gutenberg/active/)
 * [Unresolved Topics](https://wordpress.org/support/plugin/gutenberg/unresolved/)
 * [Reviews](https://wordpress.org/support/plugin/gutenberg/reviews/)

 * 0 replies
 * 1 participant
 * Last reply from: [John Huebner](https://wordpress.org/support/users/hube2/)
 * Last activity: [7 years, 7 months ago](https://wordpress.org/support/topic/poor-documentation-is-1-fail/)
 * Status: not a support question