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
- My API 101 Workshop At @APIStrat In Chicago Next Week
- Some Advice For The Enterprise When Beginning Your API Journey
- Machine Readable API Definition Format Swagger Matures to 2.0
- How Do We Continue Moving Green Button Data And APIs Forward?
- Beyond Public APIs In Government: Internal Access to Resources
- Can You Show Me The ROI On All Of This API Stuff Before We Commit
- In The Future APIs Will Be Default For All Cities
- No Public APIs Are Not Going Away Just Cause A Few BigCos Fumble At It
- Internal API Search Engine For Everyone At Your Company (Not Just Developers)
- If You Need Assistance With Your Healthcare API Strategy I Have The Person
- Explaining APIs To Senior Leadership: Access To Company Resources Without The IT Hassle
- A Conversation With @ijroth, @dorkitude, @antonyfalco, and @medjawii In The Next Generation API Stack Panel @APIStrat
- API Evangelist Thoughts On The Right To An API Key And Algorithmic Organizing
- Explaining APIs To Your Senior Leadership
- An API Evangelism Strategy To Map The Global Family Tree
- Thank You For Your API Evangelist Blog(s)
- Video From The Hypermedia Panel At API-Craft In Detroit Last Month
- Please Open Source Your API Before Shutting It Down
- Explaining My Work Around APIs In Higher Education To Institutions
- You Can Have An API Just By Choosing Products And Services That Have APIs
- Using Excel As An API Datasource And An API Client For The Masses
- Brewing Up Something Awesome With The Jive Software API
- Relationship Between APIs And Containers
- Real-time and Visualizations Will Be Key in Financial API Deployments
- Notification Focused Startups Within Leading API Ecosystems