Why Developer Engagement is stuck in the Dark Ages, and needs a rethink

Ashwin Shankar

I’ll be honest. I’m getting a bit sick of seeing “Hello World” and “ToDo List” examples and little else when exploring new technology platforms and services. It seems almost everywhere I look, the majority of new tech products/services seem to promise the “most awesomest, amazingest, supercalifragilisticexpialidocious-est technology” that can change the world, and it’s so easy to use that all you need to do is run through a Getting Started section, a couple of basic tutorials (HelloWorld and Todo List), and BAM… you’re ready to conquer the world with your super-awesome idea.

Sounds nice, doesn’t it? Except, for one thing…

It’s a bunch of bull (most of the time).

Here’s why.

Developer Engagement Sucks Big Time

When it comes to documentation and developer adoption efforts, a surprisingly large number of platform and service providers seem to believe that it’s enough to show a “HelloWorld” or “ToDo List” tutorial or two, and developers will magically start adopting their platforms and do amazing things with them. Some will certainly do that. But what about the rest, who may not have the necessary aptitude or experience to grasp the nuances and extrapolate from the basic tutorials?

Some developers will put in the extra effort to build their competency, and build real-world applications after some struggle and a lot of trial-and-error. Often times though, most developers will end up going with platforms and services that are easiest to use, not necessarily what may be best from a feature/capability perspective. The learning curve dictates whether your adopters will stick with you or turn to an alternate solution, which may not be as powerful, but is easier to adopt. It’s a tradeoff between capability and efficiency of implementation, which efficiency will usually win.

In this era, with so much competition and rapid innovation, can technology platform and service providers afford to allow so many potential adopters go somewhere else?

I’ve decided to write this post not just to bitch about wishing learning curves and technology adoption would be easier for me and my developers. I’m writing this because I’m seeing that there are growing skill inequalities in talent coming into the market, and we’re fast reaching the tipping point of startups and developers being forced to “dumb-down” their stacks as they’re not able to find talent that can work with their ideal tech stacks, and they also can’t afford to delay implementations while waiting for devs to navigate the learning curves involved in adopting better suited technology.

We are living in an era of the tech platforms and services. The multitude of options for almost every conceivable platform and service scenario makes the current marketplace a smorgasbord of infinite possibilities for developers. From infrastructure services, to managed databases, to tools that let me build amazing cross-device applications, there’s very little stopping developers from creating amazing applications every day.

As technology becomes more mainstream and integral to our very existence, the sheer number of potential developers that companies can target is only going to grow. However, this increasing pool of potential adopters and customers is going to result in an even greater gap in capabilities and skills, to the point where the success and failure of technologies is not going to just be a factor of how well it solves a problem, but of how easy it is for developers to grasp it’s nuances, and how quickly they can build stuff with it. I’d say we’re already reaching that point now.

Which leads to the question,

“Are tech companies doing enough with their documentation and developer outreach to ensure that developers spend enough time to successfully adopt their platforms/technology?”

I don’t think so, and I don’t think I’m in the minority on this.

Just saying your tech is easy to use, and targeting a handful of your potential audience is not going to cut it.

It’s not the fault of the people who build these tools and products that the current generation of developers isn’t as readily skilled as in the past. But, they can’t afford to ignore this trend, and continue doing things the same way.

Explaining the epiphany

I’ve come to this opinion as a result of my experiences of the past few months exploring quite a few new platforms, from Cloudant(IBM’s NoSQL DBAAS), Auth0 (Identity-as-a-Service), AWS’s Lambda stack, API-based shopping carts, some (micro)frameworks, to new versions of established tools like the latest versions of Angular and React. In a lot of these cases, I’ve come away with a feeling there seems to be something missing in the quality of useful tutorials and getting started docs, and there’s a gap between the getting started material and the detailed documentation, where the whole intermediate level of exposure isn’t being addressed.

I wonder if anyone has considered that when it comes to the developer documentation and outreach, the UX sucks in most cases. (Come to think of it, why don’t more people treat documentation and developer adoption as a UX problem? I’ll leave that aside as a topic for another rant.)

A lot of documentation out there is very pretty to look at and seems very comprehensive (in volume), but in terms of its primary purpose of helping readers grasp how to use the products/services, it can be a disappointment. Rather than try to showcase how amazing and versatile a technology or service is by using tutorials and real-world examples, and providing starter kits which I believe are extremely valuable to sealing adoption with developers, the documentation either is scant or overly exhaustive with a mind-boggling amount of technical details and nuances, but little practical reference.

Pointing some fingers

AWS, for me, is one organisation that I think is particularly guilty of the latter. I say this with all the respect and admiration as an AWS fan (no sarcasm here, I’ve been singing their praises since 2007, and I still do). They have some of the most exhaustive documentation I’ve ever come across, and yet at the same, it’s sometimes the most useless for solving a particular problem. The trouble seems to be that there seems to be a lack of clarity at exactly whom the documentation is targeted at.

In AWS’s case particularly, a lot of the documentation for new services is extremely technical to the point it almost reads like a research paper by a Phd or Masters candidate. At times, it feels like the mental equivalent of the signs at amusement parks where they say, “You must be this tall to get on this ride”. I get that its technically complex, but sometimes I just want to know how to use the damn thing, so show me. I’ll get around to the theory of whats going on with it and explore the tons of parameters and options later on.

I certainly felt this way when trying to understand how to use AWS Lambda when it was launched in 2014. For some reason, the documentation was just too obtuse for me to grasp how to use it, and I desperately looked out for some tutorial or sample code to help illustrate how to use the platform. It took a few months for me to find a great tutorial on how to use AWS Lambda. A few days after that, I deployed my own test platform to validate an idea, and I’m now building a new service around it.

An organisation like AWS, which is a market leader, can probably get away with not worrying about being accessible to everyone as they have enough users who have the exposure or willingness to adopt their services, but surely not everyone can afford to get away with this? But it seems like that’s what a lot of people out there are doing.

Which made me consider, “How many people start out with trying to learn a platform or service, but opt for an alternative instead, as it’s easier to learn and use?” I then had to wonder how often this happens simply because devs feel there’s not enough material beyond the ‘Hello World’ examples, to help the devs build competency and familiarity fast enough.

I’m sure this is also a factor in why we’re seeing so many new products and services which are very “similar” to existing offerings in the market, but which seem to address very specific gaps found in competitor offerings. I’m also sure they end up poaching a lot of users from the existing players, simply because they do a better job of making it easier for developers to build stuff for the real-world.

One example of a company successfully improving on existing offerings is the Meteor Framework (www.meteor.com), which has been a revelation in the NodeJS frameworks market. They have built a very passionate and vocal community of users around it, many of whom have no prior experience with NodeJS. Their developer outreach is phenomenal, with an amazing collection of samples and tutorials, and they have a great group of volunteers who actually contribute as much as the core Meteor Developer Group to the success of the framework.

But what about Support?

I’ll admit that a lot of companies do try to address this issue by offering support channels for developers to reach out and get clarifications from experts, but in many cases these are considered revenue streams as well, which turn out to be counter-productive as it creates a barrier to a lot of people to get in touch with the companies, and they seek alternative channels which are free. It’s one thing to charge for support from a customer who’s committed to the technology/platform, but for someone who’s still getting to grips with the stack, and evaluating the platform, it’s not going to be a first choice.

Yes, the companies can’t offer the same level of support for committed users and non-committed users, as that’s not scalable. But, at the same time, they need to do more to take more ownership of the process of converting vacillators to customers.

The other problem is that traditional support channels require devs to ask the right questions, and often that pursuit of a right question in itself can take forever, leaving the developer tired and frustrated at the lack of progress, often leading to an exploration of alternatives that might not be so hard. I accept that you could address this if people paid to help address this shortcoming, but as I’ve mentioned above, there’s a greater likelihood of people looking elsewhere for answers for free, rather than paying for answers.

Leaving it to communities like StackOverflow, etc. to address the issues faced by these vacillators offers no guarantee of a good user experience that will result in conversion. Treating this as UX problem is critical, IMO, to the successful adoption of these technologies.

Ok smart guy, got a solution?

There is a solution to this, in my opinion. One which is quite practical, and fairly easy to implement.

Sample code and fully-functional examples. Lots of them. The more real, the better.

The more sample code, examples and starter kit templates a company can share on how to use their platform, the more opportunities they are creating for developers to see the technology in action in the real-world, and to also use these samples as starter templates for their own projects. These tools inspire people to build new products of their own, and also make it much easier to get started and start seeing results.

I’ve certainly seen more people spend time on technologies if they are working towards a real goal vs just following some basic tutorials, and then having to figure it out on their own.

The big picture perspective

With the mainstream rise of paradigms such as Agile Development, Lean Canvas, etc., the development emphasis is on getting things done fast, not just on getting it right. We can get things perfect and right down the line, but right now things need to get done fast.

And in the tech world, the companies that accept this emphasis, and focus on ensuring their adopters can meet these expectations, are going to be winners in the great game of developer adoption.

Time is money after all, especially in the tech world. And where it ends up impacting on development adoption and implementation timelines, its a matter of survival.

This is my view anyway.


For a lot of you reading this, I’m sure what I’m saying here isn’t anything new, and might seem a bit self-evident to write to about. But, it’s amazing how many tech platforms and services are still vulnerable to loss of adoption simply due to ineffective, old-fashioned developer adoption efforts and documentation.

Just to set the record straight, I’m not dismissing any of the tools or vendors I’ve mentioned here, and I’m still proceeding to use most if not all of tools I’ve mentioned above. But the effort required to get to a point of competency has been much more intense that I’ve faced in the past, and I doubt that I could have managed to come that point without external sources such as forums, StackOverflow, GitHub Issues, and Googling in general, on which I’ve had to rely on a lot more than ever before.

This latter point is why I started thinking of whether the companies are doing enough on their own to ensure developer adoption, and where I think a lot of them end up failing. A lot of companies are doing what I’ve highlighted here, and more, to address the developer skill gap and doing very well, but there are even more who don’t seem to have gotten the memo that they need to step up and make it easier for people to use their products and services, as fast as possible.

Ashwin Shankar

Written by

Co-founder @atworksco, owner of a monkey brain who codes, homebrewed behavioral economist #talkhistorytome #startups #impactideas #footballaddict #ynwa

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade