Please provide advanced documentation

• 21stcn

• June 30, 2018 at 10:25 pm

I have been working with ACF for years but I am getting increasingly frustrated with the basic level of the documentation. I understand you want to keep it simple and accessible for most users, but there should at least be advanced documentation somewhere which follows the same patterns in terms of specifying exactly what a function does.

For example, while I have used the function update_field() 100s of times, I still forget what exactly is returned in the different situations, say, if field exists but has same value, if field does not exist, etc.

When I visit the docs https://www.advancedcustomfields.com/resources/update_field/ , I end up reading the whole thing over again just to try and find what the possible return values are so I can cover the responses in my application. The return values are not specified, so now I have to literally test all permutations myself again, write my own docs, or continue using google until I find a problem where someone has received an unexpected return value.

Please read the documentation page linked above. There literally is not a single mention of a return value. How is any developer meant to start using this function after reading the docs without a single suggestion of what might be returned, aside from testing all variations?

Every single function should have the basics explicitly specified somewhere. It is really that simple.

While I understand you want to keep ACF simple, given the actual complexity of the plugin and as a long time paying customer I feel the documentation is completely inadequate. I am really sick of testing for responses from functions. Please just compile proper documentation that covers the bases.

• Monolith Collectiv

• July 6, 2018 at 7:34 pm

I think this way to harsh, I’d like to have a more complex documentation myself and would love to have it as a PDF aswell so that I can develop without internet connection on the road.

But Elliot is giving this plugin away for free and the Pro Developer Licence price is a Joke compared to other less use-full plugins, imho it’s the best there is, you can do all with it.

And if you all-ready are writing your own docs why not share them with Elliot so he can add them. The documentation is the best for a plugin I have ever seen, of course some things are missing (which Elliot covers sometimes on YT).

• 21stcn

• July 6, 2018 at 11:20 pm

I think you are right: my tone was inappropriate. I suppose I was frustrated at the time having to read through ‘update_field’ for the hundredth time.

Ultimately I believe two things though.

1. The ACF team do what they do for profit and there is nothing wrong with that. The free version is an on-ramp to the amazing full version which is ultimately a consumer product. While I agree with you that the prices are ridiculously low, this is their chosen business model and it doesn’t change the fact that they are selling a product and providing follow-up services, most of which, like this forum, are fantastic. Bottom line, ACF is not a charity organisation or NGO. The low price does not excuse deficiencies in the product.
2. Secondly, any decent documentation should specify the parameters and return values in a systematic manner, eg: https://codex.wordpress.org/Function_Reference/update_post_meta . This is standard practice across the coding world because it is so obviously necessary. ACF has been around long enough to simply lay out these items in a standardised way for the sake of developers. I don’t think it is too much to ask. If it were an open source project I might consider changing the docs myself.

I agree with you that I am being fussy but I stick by my point that the ACF team should improve their documentation, or provide supplementary advanced documentation, for the sake of their developer customers. Simply specify the full set of parameters, return values, types, caveats, etc.