ISE Blog

Best Practices - Treat Your SDK Like You Treat Your Code

Developers often work individually or in a larger team to produce products for a variety of consumers.  Sometimes it’s a web app, a mobile app, or perhaps software for an overall system that includes some hardware.  When developers are creating something that will be out on the marketplace they know it will reflect on them or their company, and have an impact on whether or not trust is built in the marketplace.  In this scenario, documentation in the form of help menus or instruction manuals may be extensive to make sure the user experience is ideal and that any issues or concerns raised are promptly addressed.  In contrast to this, when it comes to working with other developers through documentation or direct support, completeness and attention to detail can often be lacking.

When a company or group of developers creates a platform that others can develop on top of – think of a smartphone or console gaming system as examples - how other developers will interact and work with that platform is defined in what’s called a software development kit or SDK.  The SDK provides a variety of items for developers working with the platform that could include tools, documentation, processes, code samples, libraries, APIs, etc.  The customer of the SDK is another group of developers.  Unfortunately, one of the most common areas for poor delivery in the form of incomplete or inadequate documentation is often an SDK. 

In reviewing an SDK, developers often find a variety of problems.  These problems can be something minor such as typos, or something major like not mentioning whether a library is thread safe or a code sample that is inaccurate.  Other fun potholes in the development road include incomplete definition of potential return values for various methods, or the always fun changing API that is inadequately documented as future updates are released.  A developer relying on the SDK needs a product that is as well polished as a consumer device and support from resources when there is ambiguity or questions.  Sadly, this sometimes does not happen.  Unsurprisingly, while developers get excited about coding, solving problems, and delivery, often they are less enthusiastic about documentation and support.  Being the authors of the platform and documentation, their familiarity can lead them to not understand what is lacking and being resistant to updating based on consumer need.

To drive home the importance of a thorough SDK and supporting it, consider the following hypothetical.  Suppose a development team creates an app for smartphones - call it the Acme HappyApp.  They architect, design, implement, test and finally release the product and everything is great.  As platform updates are sent to various smartphones, they take the time to review any SDK updates in advance of the release to ensure they do not need to update their application.  Everything is still looking great, no updates needed.  Suddenly they start getting contacted by users, first just a few but then hundreds a day.  They are told whenever the users open their app their smartphone calls the closest pizza place and it can only be resolved by pulling the battery. 

Pizza OvenBefuddled by the calls to pizza parlors everywhere the team digs in and determines the steps for reproducing the problem.  They find that when users change the language of the app from English to Lorem Ipsum things go haywire.  The developers investigate the SDK, they verify they are doing everything correct, so they contact the support teams listed in the SDK documentation only to be met with the cold shoulder.  Read the documentation they say.  Everything is fine in our code they reiterate.  Clearly you are doing something incorrect in your app they are informed.  None of these messages come across with a sense of concern or acknowledgment there could be an issue with the platform. 

Days go by, users still aren’t happy with Acme HappyApp and the HappyApp team isn’t happy with the platform team they’ve been in contact with.  Then the HappyApp developers figure it out.  The providers of the SDK failed to note that their Lorem Ipsum language isn’t thread safe.  In fact they indicate the opposite.  It was a cut and paste error from another portion of documentation.  The HappyApp team wasn’t crazy, they had done their job, followed a great process, and their reason for getting blasted with support issues was nothing other than poor SDK documentation.  They issue an apology, but note the issue with the platform.  As a result, the platform team has a lot of egg on their face and some explaining to do to the market.  Their brand and level of trust has taken a hit not because of a coding error, but because they failed to understand they aren’t just developers, they are providers of a service to customers.  When they treated the customers – other developers – poorly, they got dinged. 

In the hypothetical example above the platform developers failed to treat their SDK like they treat their released product.  The problem was then compounded with poor support.  Anytime you release a platform it is important to treat the SDK with care and more importantly listen to your consumers (other developers) when they ask questions or raise concerns.  Checklists for ensuring a great SDK can be found via the web and if you’ve found a valuable SDK you use then let it be a model for your team.  In reality all the technical knowledge in the world isn’t worth much if you cannot communicate and support the audience using it.  Keep that in mind and you can go from delivering duds to delivering a five-star product and being proud of your work.

Do you have additional best practices you use?  Comment below and share your ideas!  Have an IoT project you are thinking about creating? Give us a call and we’ll make it a success. 

Hudson Ludvigson, Senior Software Engineer

Hudson Ludvigson, Senior Software Engineer

Hudson Ludvigson is a Senior Software Engineer and the Practice Lead in Vehicle Telematics at Innovative Software Engineering. He has been with ISE since March 2006. He enjoys the diversity of the software engineering field and how it impacts and improves peoples' everyday life, particularly in the domains of agriculture, business, finance, and medicine. In his downtime he can be found enjoying college football and outdoor recreational sports, or spending time with his family.