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?
Enormous Impact
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.
Extreme Variety
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
Conclusion
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.
