@ikai pointed out an unintentionally funny article The Real Reason Silicon Valley Coders Write Bad Software. The reason? Because they aren't better English writers. This article made it into the Atlantic, a literary magazine. Thus, a bunch of self-congratulatory literary types can cluck at the programmers and say "If only they appreciated my skills, the world would be a better place." This article is bullshit; there's more to designing a good API than writing English. I say this as a writer with pride in his craft: Writing isn't everything; it's not the most important thing; it might not be in the top five.

A superb API needs almost no documentation; it just works. But if you ask the designer of that API to explain it with words, they might stumble. If you're going about day-to-day life as an engineer, you encounter these APIs, but you don't notice that they were written by folks who can't string sentences together. A good API is almost invisible; you use it smoothly, without thinking about it. You don't look for documentation, let alone read it; you don't ask the API's author for an explanation. But if you're a technical writer, you might bump into these cases. You might be researching a document and ask "Hey Sandy, you wrote this FooBar API—I'm supposed to write something up about it, since it's one of the most-used APIs around here. What's it for?" Sometimes it turns out that Sandy can't explain FooBar so well. Does that make me respect the API less? Heck no, I'm still glad to use a well-designed API.

A medium-good API benefits from good documentation, instructions on how to work around the rough edges. For these APIs, folks notice bad documentation; it can make the difference between figuring out how to use the API and failure. It's tempting to say that if only the engineer could think through complex lines of reasoning, that this API would be better. But more likely, the engineer wasn't done learning about the problem the API was designed to solve.

A bad API is hard to use. So you read the documentation for hints. The documentation confuses and enrages you. It's hard to tell whether that's because the documentation is bad or because it's accurately describing a tangly system. But you know that you were reading the documentation when you lost your temper, so you blame the documentation. You blame the engineer's writing skills. You lose sight of the important things.

The skill most important to designing APIs? It's API design. Hey, painters, is this what it was like to read Hackers and Painters? (Do I know any painters? Do I know any painters who read this far in a rant about programming?)