Feel free to open an issue to let us know which parts of the documentation you find obscure and if you have suggestions for how to improve them. We did a larger overhaul a few months back and are always open to feedback on how to improve it further! https://altair-viz.github.io/

(disclaimer: I'm a co-maintainer of Altair)