APIs, Code, and Using English in Documentation

I am not, by any means, a capable coder. I can put together some basic scripts, but nothing complex. A complete novice in other words.

But I like to try and figure things out.

Which is why this observation from the Atlantic made me nod my head in agreement (“The Real Reason Silicon Valley Coders Write Bad Software“). Writing skills are necessary in all fields.

The computer world is based on using APIs. Zynga uses the Facebook APIs to embed its games on FaceBook. Any iPhone or iPad app uses the iOS API to let you move stuff by swiping the screen. WordPress is built on a series of APIs that lets just about anybody build a web site in minutes.

However, even the best of these APIs are hard to use because the documentation, supposedly written in English, is terrible. Most engineers can’t write a single coherent sentence, never mind string together a paragraph.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Recent Posts

Perspective

I didn’t really know Sarah until January. We both had vague memories of our time in Brazil 30 years ago (“You always had a backpack” she would remember, which sounds about right. “You were tall and loved to dance” I would remember. Which also right.) No matter. She was part of the most amazing (and exceptionally eclectic) crew of former Rotary Exchange Students participating in our reunion this year. And everyone loved her. She also was dying.

Read More »

Checkin. During a break.

Whatever happens, there will always be people who say: It’s all completely awful, and others who say: It’s all a complete joke. Koos Van Zomeren.

Read More »