After adding (and tightening up) @spec and @type attributes on a 10 KLOC project, I felt confident enough of my typespec-fu to write up an introductory article: Elixir, etc. - Typespecs
I offer it here in the hope that it may save others pain and encourage the use of this tooling.
-r