API designers should be writers

  When I was an freshman in college I took a required writing course. Good idea. If you can express yourself in writing your professional life and maybe your personal life will be more rewarding. Catch em while they're young.
  I don't remember the teacher's name, but I remember her lesson. Say it directly. As you revise, look for words you can take out remove without changing the meaning. You'll be more persuasive, and better understood.
  I find, to this day, my first drafts have a lot of extra flowery bits that don't do anything for the reader. It's as if while I'm drafting the prose in my head I need extra words to help pace myself. There's always a rewrite coming, and the text always gets shorter as a result. So I don't try for economy in version 1. (I made some of the edits here with strikeouts to show you how it works.)
  The same economy is important in designing APIs.
  I've been working with an Amazon API the last couple of days. They could use an editor. There are extraneous concepts in their APIs that don't help anything, just add confusion, and inefficiency, and raise barriers to adoption.
  Another rule that API designers violate -- the easy stuff should be easy and the hard stuff should be possible.
  Too often you have to master the most complex part of the API before getting Hello World to work. Very frustrating. I may never need to set a hundred DNS values in one shot. Yet, I have to understand how that works just to establish a value for a single CNAME.
  Another thought occurred to me about the art of programming, related to this subject. Why do we change the rules every five years? I know, it makes older programmers obsolete faster, and the younger guys like that. Heh. Nice. But look at baseball, another game that favors the young. The rules change very slowly. To me the DH rule in the American League still seems new and controversial. Maybe it does to you too. Yet it's been around 38 years.
  We rip up the pavement far too often. I know I've been saying this for decades. But we're still doing it.