This YouTube video on maintainable code set my hair on fire. These guys usually have something interesting to say but on this subject they are a bit naive.
Writing the documentation first is also false. While it's nice to say it's impossible in practice. See Knuth's books and essays on programming languages. Finally, the whole thing begins with requirements gathering. I developed an environment that would allow the analyst to define the flow and sometimes the signatures. Then the programmers would work on the algorithms.
The reality and by extension the erlang way... make it work simply and then refine it.