Godot-docs: AnimationPlayer advance/seek difference

[golddotasksquestions]

Hi! I've just wasted 4 long frustrating days with incredible effort to forensically isolate a single bug, until I eventually narrowed it down to the AnimationPlayer and that it seemed to trigger Call Func Track keys even when it should not. I used advance() to jump to later parts in the animation, because I have done so without a problem over the past months. Only this time in included Call Func Track keys.

Believe me, I've visited https://docs.godotengine.org/en/3.0/classes/class_animationplayer.html probably a hundred times.
I never understood the difference to seek though, and I still have no clue what "updates at process time mean" vs "updates too" supposed to mean. Because the difference was anything but clear, and because advance() worked just fine, I kept using advance(), when in actuality, as it turns out, I should have in pretty much all cases used seek(). Thanks to @Pobega for verifying with the source code.
Seek does not trigger Call Func Track keys. How should I have known this behavior when it is not listed in the documentation?
I'm writing this in hopes to give the people who write documentation an understanding in how beginners like me will look at the documentation, and I hope you will take it into consideration when writing documentation. I don't know if advanced coders would have guessed by the name alone how advance or seek behaves, but beginners like me need things spelled out. And even if advanced coders could guess it, isn't eliminating the guesswork the point of documentation?
https://github.com/godotengine/godot-docs/issues/2190

[Pobega]

Poking around in the source, I see that doc/classes/AnimationPlayer.xml mentions ANIMATION_PROCESS_MANUAL, which says "Do not process animation. Use the 'advance' method to process the animation manually." Perhaps some of this information should be exposed via https://docs.godotengine.org/en/3.0/classes/class_animationplayer.html#class-animationplayer-advance

I think it may be good to specify that AnimationPlayer::advance() is a 'fast-forward' of sorts and AnimationPlayer::seek() actually skips the changes between the two points, but I'm pretty new and not familiar enough with the Godot nomenclature to be helpful here.

[golddotasksquestions]

I would like to add though that

"Do not process animation. Use the 'advance' method to process the animation manually."

would leave me as confused or even more so than before, if that's all the wording and explanation we would get.

I think it may be good to specify that AnimationPlayer::advance() is a 'fast-forward' of sorts and AnimationPlayer::seek() actually skips the changes between the two points

Yes, exactly!
AnimationPlayer::advance() is actually an instant 'fast-forward'. It seems to do it within a single physics frame. Which is why I was so confused about the difference to seek().

[Pobega]

I attempted to open up a PR to explain this a bit more, but it looks like the pages under classes/ are a special case and shouldn't be edited here:

Note that the pages in classes/ should not be edited here, they are automatically generated from Godot's XML class references.

I'm not sure if this means I should open up a PR against Godot proper, then? Can anyone advise?

@golddotasksquestions , let me know if this wording is clearer to you: https://github.com/Pobega/godot-docs/commit/854c919eb69a6a305a60a86fb9108a419ba29feb

[clayjohn]

I'm not sure if this means I should open up a PR against Godot proper, then? Can anyone advise?

Yes. Although you will need to redo your PR in the original xml file in the godot repo. https://github.com/godotengine/godot/blob/master/doc/classes/AnimationPlayer.xml

I'm writing this in hopes to give the people who write documentation an understanding in how beginners like me will look at the documentation, and I hope you will take it into consideration when writing documentation.

@golddotasksquestions Just to give you a little perspective, these sorts of issues in the docs are not because the doc writers don't think about beginners when writing docs. When writing docs _all_ we consider is how new users will understand what we have written. That being said it is extremely difficult to anticipate how others will interpret what we have written and mistakes do happen

[golddotasksquestions]

I know, wording can be extremely difficult, especially the larger the demographic is you have to keep in mind. Still, quite often it just feels like the documentation has been written by advanced coders - for advanced coders or some other in-group.
There are examples where this is less the case, see https://github.com/godotengine/godot-docs/issues/2190 @clayjohn

[clayjohn]

Still, quite often it just feels like the documentation has been written by advanced coders - for advanced coders or some other in-group.

I assure you, that is not the case. Hardly anyone works on documentation and those that do, do it out of a deep desire to help new users. Working on documentation is very challenging and it is incredibly thankless work (as you can see from the reddit thread you linked).

Most of the flaws in the documentation are not from lack of good intentions, we would all love to have docs as comprehensive and accessible as gamemaker, however, the amount of work required makes it impossible. But we still do our best.

[Pobega]

https://github.com/godotengine/godot/pull/26354

This is merged into master

[akien-mga]

Thanks!