I'm incredibly frustrated by the documentation provided for app developers. This should be a really high priority for Fitbit, as a rapidly expanding app ecosystem is a big part of the success of new devices - especially ones in amorphous categories like 'Fitness Tracker' and 'Smart Watch'.
I am an experienced developer who is very proficient in multiple languages. My job title in my day job is Lead Developer. I only say that so that this post isn't dismissed out of hand.
I bought an Ionic - even after reading bad reviews - because I wanted to develop Fitbit apps. I loved my Charge HR and Charge 2 - and I have bought Fitbit devices as gifts for various members of my family. I only say this so that I'm not dismissed as a Fitbit hater or something like that. I *really* want to love developing Fitbit apps because of how much I like the platform as an everyday user.
Learning to develop Fitbit apps is like going to the dentist. Really. The user experience as a developer is absolutely terrible. The documentation initially looks good, but there are huge gaps that become really obvious over time. I find myself coming to the forums for examples for something relatively simple again and again. Things that absolutely should be in the documentation, like "How do I define and show different views in my application", or "How do I interact with my device from a companion app", or even "How do I append to a log file". It blows my mind that the last question isn't clearly answered in the Filesystem API documentation.
So the next step for most new devs is to go to the developer forums and search around. That isn't a great experience either. Many of the things I search for are only answered by community developers like myself. Thank god for them though because without their help I'd have twice as many unanswered questions. Many of the responses from the few Fitbit developer employees who post regularly are just links to someone else's example in a Github repo, with zero explanation. So then you have to go through that repo file by file until you find something that looks like it might be what you are asking about. Think about what that experience is like for a new developer who is still learning Javascript, HTML, CSS, etc. Chances are you just lost them.
For a device whose main function is logging data from sensors, there should be an example of how to append data from selected sensors to a continually growing logfile that gets picked up by the companion app in some definable interval of time, and uploaded to the Web API in a way that is easily graphed and styled like the built-in apps. In fact, the API should have higher-level functions that make this stupid easy. That's another big part of what is wrong here - the API mainly exposes low-level functionality of the various components (device, companion, settings, web) and has very little high-level orchestration. That burden is put upon the individual app developer, who is expected to do this with huge gaps in the documentation by digging around in the developer forum and searching through Github Fitbit repos who usually don't specify what version of the OS or API is used or required. This is unacceptable if you are trying to attract new developers - especially folks who are new to Javascript.
Here's some recommendations that will probably just get ignored:
- You need to hire a full-time developer community manager who is tasked with:
- Analyzing the questions coming in from developers that reveal gaps in documentation
- Assign those gaps to a full-time Technical Writer (NOT - I repeat - NOT a developer! Developers are *TERRIBLE* at documentation. It is not in our bailiwick to create documentation - hire a really good technical writer it will make a *HUGE* difference)
- The technical writer will work with the developers who have expertise in the areas needed to create documentation. This should be priority work - don't make the technical writer fight with the developers to get their job done. A developer from each focus area could be assigned to work with the technical writer for 1-2 hours a week and a lot could be accomplished that way.
- Complex things should have an example application that clearly illustrates the principle being demonstrated with good documentation of what each part of the app is doing.
- Guides and tutorials that show code examples should say the name of the file in which the code should be placed. The existing documentation relies heavily on a developer to recognize that the code being shown is Javascript, HTML, CSS, or SVG, and what file(s) the code should be placed into. This is a huge advantage of a downloadable example versus a "Guide" or "Tutorial".
- Each Guide/Tutorial should really have a downloadable example. A developer should create this and provide it to the technical writer to insert it into the guide/tutorial.
- The technical writer should work with the website developer to get their work on dev.fitbit.com ASAP. Seeing more documentation appearing on the website over time gives a good impression to your developer community. They work (mostly for free) to make your product more useful, so this is really important.
- Create some high-level functions in the API that take more of the grunt work off of app developers. Like I mentioned earlier, probably 90% of apps log data to the device, which needs to be transferred to the companion app on the phone, which can post it to the Web API where it can be graphed and styled like the built-in apps. This should not require as much boilerplate code as it currently does. These should be Lifecycle events that occur periodically rather than discrete timers that an app developer has to create.
- Expose all of the sensors on the device to developers. This is really a no-brainer. The CPU probably has a temperature sensor, for example, and the SPO2 sensor (which I notice is no longer on the spec sheet on Fitbit.com for the Ionic) should be exposed. All sensors should be documented on the spec sheet, and all should be available for community developers to use in their apps. Trying to keep some of the sensors only for use in apps made by Fitbit is a bad decision that will limit the versatility and diversity of the app ecosystem. It will also irritate your community developers, because they will either be unable to implement their idea for an app, or they will have to do metaphorical cartwheels in their code to do it another way if they can - and sometimes this will result in more battery usage. Both of those are bad choices.
- The companion app on the phone should have access to more of the phone's capabilities. Some would say this is a big ask, but it exponentially increases the power of the application ecosystem. As new sensors and capabilities are added to phones, those would become available to your developer community for integration or interaction with Fitbit devices.
As I said above, I fully expect that my recommendations will get ignored. I also expect that there will be responses to my post that I am anti-Fitbit or that I don't know anything about development. I'll probably get responses that I'm a **ahem** or don't know what I'm talking about, or that I'm asking too much of Fitbit with my suggestions.
So anyone who is about to reply to this post with any of those types of ad hominem attacks can save their keystrokes for something else - I will ignore any responses along those lines. I'm putting forward my viewpoint and suggestions, and I don't really care if anyone dislikes or disagrees with them.
I really want to see Fitbit succeed, and I think they have a really unique niche in the Smart Watch/Activity Tracker space. I don't want to see them get eclipsed by their competition. I'd love to make compelling, useful apps that contribute to the power of this platform, but some serious work is needed to empower and grow the developer community.
Fitbit Developers oversee the SDK and API forums. We're here to answer questions about Fitbit developer tools, assist with projects, and make sure your voice is heard by the development team.
Best Answer
