Editorials

Documentation

I was reading an editorial on LinkedIn on the topic of API documentation. https://www.linkedin.com/pulse/api-documentation-iot-quantum-leap-usability-paradigm-ghersi.The primary position of the author is that as software becomes more segregated, and connected through APIs such as RESTful services, the need for documentation becomes more important than ever.

Furthermore, the documentation needs to not only express the API implementation, but also provide the consumer with the ability to find the help they need quickly, and be able to see/copy good examples of how the API should be consumed. While it is important to be able to understand the architecture of the API, it is more important to understand how to perform specific tasks.

Today I had an experience that causes me to jump on the bandwagon. I was working with a library that has a great deal of documentation. It was very thorough. However, all of the documentation was full of terms and concepts that were never defined. Definitions and explanations were based on terms and classes that were not defined, or the object being defined. I had a specific use case. The library was supposed to be able to implement that use case. But the explanation was so internal as to be completely useless.

It reminded me of a joke that was popular years ago. It goes like this. A pilot was flying one day, and clouds came in quickly so that the ground was not visible. The pilot got on the radio and contacted someone on the ground who could hear his plane. He asked the person on the ground where he was. The person on the ground replied, “you are flying in an airplane”. The pilot immediately landed in Redmond. How was he able to do that? The person on the radio worked for a software company. The answer was completely accurate, and completely useless. That could only be from a vendor in Redmond.

I have recently come across the Fiddle phenomena. There are Fiddle sites for many different software languages. Using a fiddle site, you can provide working examples of your software. A good example is jsfiddle.net. I think this would be a great supplement to any API documentation. Provide use case scenarios in the documentation. Sure, provide class documentation. In addition, for a use case, add a link to a Fiddle site with a real world example. This allows the consumer to see the code at work, even modify it, and see what the result of the change does.

Regardless, the state of documentation for many languages and APIs needs to be addressed. In my opinion, the sooner, the better.

That’s my rant for the week.

Cheers,

Ben