Posted on 01-28-2012
This post comes from the SDK Bridge newsletter. I find so much value from what Peter and Jonathan do over at SDK Bridge, I always have to post their newsletter here and share with all of you.
I recently received an email with the subject "FW: boring job". It was a long email chain that started with someone casting about for someone to write API documentation. It got me thinking about how most developers must wonder why on earth someone with the skills to program would choose to write API documentation instead.
"Why" is a good question to ask yourself when starting up a new year. In fact, I recently saw a TED talk video by Simon Sinek on how the most effective people, companies, and organizations, start by thinking about why they do something instead of what. In the video, Sinek brings up examples like Apple, the Wright Brothers, and even Martin Luther King, whose most famous speech began with "I have a dream" (why) and not "I have a plan" (what).
In this newsletter, I'll talk about why we write API documentation, from how it impacts the world to how it challenges us personally. But first, here's what SDK Bridge been up to since our last newsletter:
- Writing C++ documentation for software embedded into agricultural vehicles.
- Writing REST documentation for a company that creates software for governments.
- Writing REST documentation based on OpenSocial to be able to create and manage online meetings.
- Writing IT documentation for Microsoft HealthVault.
- Peter Gruenbaum, President, SDK Bridge
Why We Write API Documentation
To most developers, writing API documentation is nothing short of torture. But to a few of us, it's a fascinating area. What gets us so excited?
In case you haven't heard, the biggest technology revolution is happening since the invention of HTML. We've all heard about the explosion of smart phone, tablet, and software-as-a-service technology, but not everyone knows that APIs are what's driving all of these technologies, providing people with instant access to data. It used to be that only the people who had the data could write the software that granted access, but with APIs, the number of software developers who can create applications with that data is vastly increased. Companies are discovering that developers are doing things with their data that they had never dreamed of. It's an exciting time to be working in software.
Ask anyone in the API industry what the biggest obstacles are to creating apps, and I guarantee that they will bring up API documentation. Good documentation results in application innovation; bad documentation stifles it. API writers have the power to get an API adopted and used.
An Interesting Human-Computer Interaction Challenge
Donald Norman, the Human-Computer Interaction guru, once wrote an interesting essay of how the qualities of human beings are different than the qualities of computers. The way that we think is different than the way that machines "think", and a good user interface bridges the gap, making the computer intuitive to the person.
When your product is a software platform, then your API and its accompanying documentation is its user interface. If you want the API to be usable, then you have to figure how to bridge that difficult gap between the linear, inflexible world of computer programming and the non-linear, flexible way that people think and learn. It's a fascinating challenge.
Writing documentation for an API is a much faster process than writing the API itself. This means that an API writer often gets to learn about something, explain it, and then move on to the next thing. In just the last two years, I've gotten to learn about eCommerce, health care, traffic prediction, agricultural vehicles, online meetings, call centers, mobile phone applications, electric utilities, and noSQL databases. I even once wrote documentation to help the search for extraterrestial intelligence.
In the near future, everyone who has data will have an API to access that data, and all of those APIs need documentation. Writing that documentation is a way to get a taste of all of the different worlds that software is touching.
On the Cutting Edge
One of the big challenges of being a developer is staying on top of the latest technologies while there is so much legacy code to maintain that's built on old technology. Often developers get stuck working in old technology, wistfully wishing they could be on the cutting-edge.
Companies like to promote their platforms that use the hottest languages and protocols. That means that they will prioritize documentation for those platforms. Not only that, but I find that writers are given even more permission than developers when it comes to learning technology on the job. Between these two, API writers often get to work with the latest and greatest technologies
Enormous impact, thinking about how people learn, extreme variety, and getting to work with cutting edge technology - it's pretty cool being an API writer these days. Of course, you have to love to write and you have to love to program. But if you are good at those two things, there's never been a better time to be an API writer.
comments powered by Disqus
Winning in the API Economy
|Download as PDF|
Latest Blog Posts
- The Emerging Landscape Of API Orchestration Platforms
- Getting Labeled A Hater On The Hypermedia Panel At API Craft
- My Discussion Today With 6 Hypermedia Leaders At API-Craft in Detroit
- Getting To Know Jørn Wildt For The API Craft 2014 Detroit Hypermedia Panel
- Hypermedia Feels Like We Are Still Learning To Communicate With APIs
- Getting To Know Markus Lanthaler For The API Craft 2014 Detroit Hypermedia Panel
- Getting To Know Kevin Swiber For The API Craft 2014 Detroit Hypermedia Panel
- Getting To Know Steve Klabnik For The API Craft 2014 Detroit Hypermedia Panel
- New Indix API KickStart Program Reduces Costs For Developers
- Getting To Know Mike Kelly For The API Craft 2014 Detroit Hypermedia Panel
- A Shared, Distributed Experience(Metrics) Layer For The API Driven Application Stack
- Showcasing Your API Integrations With Other Platforms
- Increasing The Focus On APIs In Higher Education Is Important
- Getting To Know Mike Amundsen For The API Craft 2014 Detroit Hypermedia Panel
- The New StrongLoop API Server Provides A Look At Future Of API Deployment
- Models For API Driven Startups Built Around Public Data
- Will You Add Me To API Evangelist And How To Spot The Cool Kids
- When I Remix APIs Using Swagger How Do I Deal With Authentication Across Multiple APIs
- It Takes A Team Of Evangelists To Raise An API
- Support For Only Two Creative Commons Licenses In The API Commons
- Machine Readable Terms of Service Didn't Read Applied To APIs Via APIs.json
- API Deployment For Non-Developers Using Zapier, Google Docs, and APISpark
- State of Hypermedia Today @ API Craft In Detroit
- Need A Formal API Standard For Your Government Agency? Fork 18F's, And Make It Your Own!
- CORS Makes Your API Portable And Remix-able