As dumb as this sounds... you can use typespecs as documentation even if you never run dializer. We do this at work in a legacy code base that would be painful to dialyze without errors, but it makes new code nicer to look at.
I use it exactly for this. Just use typespecs as a hint to the person looking at the code as to what is expected to be passed.
If you never do anything but read them... why not documentation?
Terseness.
Yup. One could write "It takes a string as an argument & reverses it". Or one could write "String.reverse(()". For any non trivial case, such as weird options, you'll normally write documentation anyway.
I do both. All to help me in the future as much as possible when I come back scratching my head.
Isn't there a big risk the typespecs are wrong then?