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

An image of a whiteboard with faint traces of previous writings and diagrams, creating a visually distracting pattern. The whiteboard is in an office

Attention on a Hazzy Whiteboard

Switching attention leaves residue. Sometimes I feel like I’m swimming through that residue. The schemas I’m holding need focused and sustained attention, and the cludgy remnants of previous mental states and distractions makes the thinking I enjoy turn into thinking that is exhausting (and poorly done).

Read More »