In #11219 and #11223 @dstansby headed out to provide an arrow tutorial. Since the scope of this was rather limited, it ended up as an example examples/shapes_and_collections/arrow_guide.py - which is great.

However as mentionned in this PR #11223 there are a lot of other things to consider about arrows. In the end it would be good to have something like a complete "Arrow tutorial". I'm collecting the comments in this thread for them not to get lost, once someone has more time to write this up.

There currently are already the annotation_demo example and the annotations tutorial. So I wonder in how far they are overlapping or not. Independent of that, there should be links in between them.

In addition, the following things should be considered when writing :

• what is the relation between ax.arrow, ax.annotate, ax.quiver, mpatches.FancyArrowPatch?
• Any user looking at the patches doc would directly ask: "What is the difference between Arrow, FancyArrow, FancyArrowPatch and YAArrow?" A tutorial might want to answer this.
• The problem when drawing arrows is mostly to understand all the different parameters. Common questions could be
  • How to make the head larger?
  • What are the units of head_length, head_width, tail_width, mutation_scale, etc.?
  • Why is my arrow shorter than the distance between the two points I specified?
  • Why can't I use an FancyArrowPatch in a collection? What's the alternative? (should be checked when deprecating other arrows)
  • How do I draw an arrow with a dotted tail?
  • When should I use a ConnectionPatch instead of a FancyArrowPatch?
• Is the arrow_demo useful? Can it be replaced by something simpler? Definitely explain plt.arrow's length_includes_head and possibly head_starts_at_zero -> plt.arrow start and end locations are wrong #12768
• Apperently it's not possible to get an arrow with a bolder connection path in the middle and two arrow heads on both sides? (This SO question) Need to check.