I’ve been involved in developing training materials, tutorials, videos, online documentation and even books. So I’ve gained a full appreciation of the effort involved in not only creating good documentation but maintaining it too. Rene Winkelmeyer wrote a good blog post today about developer experience and his points are very valid.
Over the last couple of years I’ve seen a number of approaches as I’ve dug into a variety of new technologies.
One approach has been to deliver a workshop to business partners. That’s okay if the business partners chosen will be cascading training down to a wider audience. But if the business partners are primarily focussed on providing services or developing products, that approach is not going to result in widespread adoption.It might result in a few products your salespeople can sell on, after time, if those trained embrace the solution the technology. But the rest of the world will probably ignore it, especially if there are gotchas or tips that are not more widely shared.
Online documentation and demos are very powerful, if the quality is high. I first came across this with Vaadin last year and I’ve already discussed that on the blog post about Vaadin. The challenge is keeping the documentation relevant and up-to-date with regular release cycles, but Vaadin have done a good job at doing that. This requires considerable investment. The strong visibility of the Vaadin developers and evangelists makes it clear there is that commitment from the providers.
With flexibility inevitably comes bad practice, but a good provider will recommend best practice approaches. There are a number of Vaadin webinars that do that, even beyond using such standard tools as FindBugs.
But if a technology is just part of a stack, there is a bigger challenge. The other parts of the stack may vary and may work differently. A Java application could be deployed as a jar program or a web application, could connect to a variety of backends, which may or may not include persistence. It may be deployed standalone or on a web server. If the provider doesn’t provide their own IDE for the developers, then that is also an area of personal choice and integration may need continual effort. If they do, it’s guaranteed to be compared to other IDEs and needs to be kept up-to-date. But beyond all of this, there is an additional challenge: if the developer cannot easily integrate the technology into their preferred stack, you’ve lost them. To do so will require specific skills beyond the technology itself. The Vaadin Bluemix challenge last year worked well to bring together the two parts of the stack - the PaaS and web development framework. Similarly Vaadin webinars have brought together complementary parts of a stack to help empower developers to take advantage of each other’s technologies.
For a fuller stack, there is a bigger challenge. Not only does the provider have to ensure not only good documentation, tutorials and evangelists to grow and empower. They also have to ensure all elements of the stack are fresh and up-to-date. The longer a technology is around, the bigger the challenge. It’s easy to get distracted by building something new and lose focus on keeping what is there up-to-date and regularly enhancing it. But adding something new means something new to keep up-to-date, which means more expense. If there are not enhancements and regular prospect of enhancements, developers may fear that area is being silently deprecated. Moving off a platform is not easy, and they often persist a lot longer than planned. But deciding a platform is not part of a strategic future is much easier, and if the applications on the platform are not enhanced, they increase the perception that the platform itself is legacy, which further reinforces that the platform should not have be part of a strategic future. It becomes a self-fulfilling prophecy and, if it becomes pervasive, the platform and its applications may just atrophy.
Sometimes it may be more appropriate to bring in other technologies as an alternative or replacement, and I’ve seen that in XPages with Bootstrap becoming the preferred UI framework over IBM’s OneUI. The technology needs to be scalable to enable that to happen and the decision needs to be attractive both in terms of financial cost and developer effort. XPages is a componentised framework, the same as Vaadin and much of what I’ve seen with Salesforce. So refreshing a whole application to a new look and feel is much easier: the framework handles it for the developer, with minimal (if any) coding changes. Change the underlying renderers, applied via a specific theme, and most if not all of the application just changes the look. Similarly for XPages, the componentised approach meant upgrading from Bootstrap 2 to Bootstrap 3 was done at the framework layer, with different renderers. Abstracting the rendering minimises the effort required and lets developers focus on functionality. It makes the application cheaper to upgrade and keep refreshed for the customer. With the proliferation of browser-based applications, minimising the cost in order the ensure they keep working on modern browsers may be more and more important for enterprise and SMB customers.
When it comes to documentation, cloud technologies like Salesforce have a bigger challenge. The cloud requires even more frequent releases and developers have no choice - they can’t choose not to upgrade, they have to get the new releases. So the documentation needs to support them, it becomes even more critical that the documentation be kept up-to-date and good quality. As I’ve started to play with Salesforce, this is an area that has impressed me significantly. Keir Bowden blogged about how Trailhead has vastly enhanced documentation and made it easier for developers to hit the ground running. The quality and accuracy of the early tutorials I’ve tried has impressed me. The combination of videos and textual instructions, with challenges in each section to reinforce learning via gamification makes it useful both as I’m learning, but I can also see it being beneficial later on. At this point I don’t have a specific project, so I’m not in the situation I was with Vaadin of diving in and referring to the documentation as and when I couldn’t work something out. That’s a valid use case for which I can’t comment on their efficacy. But from the amount of tutorials and the pace of cloud releases, it’s clear there is a huge investment from Salesforce, an investment that will be required for the long term, and that is very impressive.