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.

Visual Data

Numbers tell stories*. The difficulty is in getting them to do so in a way that humans understand.

A side project (feasible?) I’m currently working on for work is a functional, real time data dashboard. In my mind I can picture the end result of a dashboard that serves up relevant and understandable data that teachers and administrators can use to shape the direction of their school and classes.

This is an enormously difficult task. Tracking multiple variables and presenting them in a way that the average teacher, parent, and student can read requires a profound knowledge of statistics, coding, and graphic design (not to mention a bit of cognitive psychology).

Whenever I encounter such difficulties I always find myself wondering when “the big intelligences” are going to create the tools that open up possibilities for the layman and woman. For example, my mom used to balance a checkbook using graph paper and an old (2 foot by 2 foot) calculator. It took her hours. Now I just have Mint do it for me with its ever so cool graphing apps to display my spending habits (my major weakness: alt-bluegrass).

I want the app that takes datasets and turns them into stories.

Google (any surprise?) and Microsoft (see Pivot Post) are starting to tackle this problem. It’s easy to get lost in the data subsets that Google’s Public Data Explorer has available. Want to see Ohio’s personal income per capita get kicked in the face by other states? Check out this fun graph:

For a thought experiment, swap out Ohio and use students…or classes…or schools…or socioeconomic classes…or (gasp) teachers. A short, animated display of data allows you to connect the dots quickly and immediately. Google lets you upload your own datasets (but it still takes some knowhow). When this becomes drop dead easy, why not use it constantly in education?

Final datashare – I love this 4 minute history lesson that really hits home. A social studies class could do a lot with this:


__

And, in my opinion, good storytelling is good teaching.