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 exampleexamples/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 theannotation_demo example and theannotations 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 betweenax.arrow,ax.annotate,ax.quiver,mpatches.FancyArrowPatch?
• Any user looking at thepatches doc would directly ask: "What is the difference betweenArrow,FancyArrow,FancyArrowPatch andYAArrow?" 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 ofhead_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 anFancyArrowPatch 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 aConnectionPatch instead of aFancyArrowPatch?
• Is thearrow_demo useful? Can it be replaced by something simpler? Definitely explainplt.arrow'slength_includes_head and possiblyhead_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.