Why I Believe in Documentation

Jan 14 2019

I recently developed a wearable app for the Samsung Gear. I do most of my friend-to-friend communication over Facebook Messenger but there was no real Messenger interface. So, I made my own. For those interested in it, a screenshot is below. If time permits, it will make it onto the Galaxy app store.

alt text

I bring it up because I had a love hate relationship with the documentation. I was glad there was any at all, but there were many gaps and a few extra hours by the developers would have come a long way.

I would bet that there would be significantly more apps in their store (or at least higher quality) if they improved their documentation. Features like voice control should be a breeze but are remarkably painful to implement.

Consider Developer A. She has an idea for an app that allows you to track your grocery list from your watch. However, she cannot find good enough documentation and never makes any real progress. Nothing ever gets pushed to the store.

Consider Developer B. He works for Facebook and joined the Android development team. He is supposed to build out a lite version of Facebook for the gear. He gets it done, but development is slow and the final product is cobbled together and likely not forward compatible.

Both developers had the drive and resources to push out something amazing to the Samsung ecosystem. This would have made the watch and the Samsung brand more valuable. Instead, due to a lack of documentation, only one of two apps got pushed out and it still has issues.

I get this is hypothetical but I have been in situations like both Developer A and B, and it is not fun. If a company takes the time to make something open source, they should at least spend a little more time to make it usable and clean – it pays out greatly for the ecosystem. In fact, Twilio has been very successful with a developer first marketing approach.