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.
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).
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.
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.
You must be logged in to reply to this topic.
Welcome to the Advanced Custom Fields community forum.
Browse through ideas, snippets of code, questions and answers between fellow ACF users
Helping others is a great way to earn karma, gain badges and help ACF development!
© 2022 Advanced Custom Fields.