The point of the article is that if a 'smart' capability requires going through several pages of documentation, it may not worse it. It is exacerbated when: -

The point of the article is that if a 'smart' capability requires going through several pages of documentation, it may not worse it. It is exacerbated when: - you fall into an undocumented corner case - you use a dynamically typed language (the case in the article) which essentially makes it impossible to validate the client code, although the API code may be well validated. That rings a bell in me, a time I wrote a signal processing library but people preferred using Numpy directly :,(