The Changing Landscape of Developer Content
What is the first thing a developer looks at when learning a new programming language, framework, or API? Most likely, they look up the documentation. Why is it important to understand how content for developers has evolved?
Understanding the evolution of documentation practices unlocks insights for continuously valuable ways to keep developers successful through content that is searchable, scalable, and accessible.
For the purposes of this article, we define developer documentation as any output in any type of media that enables a software developer to successfully accomplish an engineering goal.
Specifically, how quickly can developers digest new information, find what they need, and how well the documentation supports how they design, code, architect, and build. These aspects of documentation are the driving forces behind the changing landscape of developer content.
A great experience: Just think of how the Stripe API Reference is regarded as the initial gold standard for developer-focused technical content. In addition to slick output, the way they kept code libraries and reference documentation up to date, just a small dynamic step behind the API programmatically, meant they were developer-focused.
Applying concepts such as an informal tone, automatically updated process, and collaboration promotes accessibility.
A rough experience: However, if you consume APIs and rely on documentation to do so, developers experience high stress when Amazon’s documentation goes down.
Business is Not as Usual
Technology disruptors in both the hardware and software space have conducted major mergers and acquisitions over the past five years signaling a shift in B2B growth and widening the audience for developer-focused content. Digital transformation requires a combination of both hardware and software architecture for the best delivery.
In the API space, these M&A’s played out as well.
A sampling list of headlines: Intel acquired Mashery. Tibco acquired Mashery. Oracle acquired Apiary. RedHat acquired 3Scale. CA acquired Runscope. Qualcomm and Broadcom couldn’t work out a deal, but Broadcom did acquire CA Technologies. Microsoft acquired GitHub. And Amazon Web Services commoditized web services and every aspect of the cloud from hardware to software offerings.
Searchable
Documentation for developers used to live in its own silo for example Markdown stored in version control internally or only as ReadMe files on GitHub repositories. With the popularization of software coding schools and courses and the rising interest in development, suddenly there was an influx of content about development. Focused, organized content, that is easy to navigate for the various developer audience types are in demand.
Community platforms (Stack Overflow, Reddit, API Community Management Platforms, Developer Portals) foster interaction among developers so that the conversation is searchable. Disparate information needs a “home” so that it is easy to aggregate the various kinds of developer documentation.
My favorite large-scale example of this is the search bar on Google’s Developer Portal. The search bar indicates that you can specifically “Search Products and Documentation” instead of returning anything outside of that set — it’s a confidence indicator that Google will serve up targeted results which is what they are known for doing. In addition, you can see a menu of all products on the Product Index page to get a 30,000 foot view of the organization of the kind of content available.
An organized structure built around a single source of truth, such as a help center, where developers can quickly find exactly what they need, is critical for effective documentation. Being empathetic to the ways developers work is essential for understanding why developer content will continue to evolve and the most utilitarian aspects will hold true over time. Now, many software providers offer comprehensive solutions that are quickly emerging to deliver the Developer Experience that matches the Developer Journey.
Developers are valuable not just because they are expensive to attract, hire, retain, and grow, but because there is a very limited group of engineering talent.
Hurry! Give them exactly what they need. Usually, a developer is searching for answers as part of a small window of time to complete a task in a sprint cycle. Uptime, the reliability and availability of your documentation, is equally important — if they can’t reach it, they can’t search it. Hosted docs are one way of reaching this metric. SLA’s may drive the thresholds home for accountability.
The best part about digital developer documentation is the ability to see analytics if you set them up to do so. These metrics measure how the documentation is being used, areas to improve, signal gaps, and provide patterns of usage so that you can improve the documentation over time. Pair documentation analytics with API usage analytics and your community engagement metrics to understand the effectiveness of the feedback loop.
For example, we can see improvements in the feedback loop by looking at the decrease in the number of API support requests and how closely it correlates to the areas of documentation traffic.
Scalable
Many enterprise organizations and even start-ups model an iceberg when it comes to API exposure. Hundreds of APIs are used internally by the application, and a vetted set is exposed for public consumption. In the field of technical communication, going to the source is key. Being able to single source and leverage content reusability means that one change can be propagated throughout the documentation for accuracy and authoring efficiency. For example, using an industry proven API specification in your API reference saves time and scales your reference documentation.
Single sourcing and reusability are also important in versioning so that you don’t have to start from scratch. Being able to reference small snippets of content that will be used repetitively can help simplify version management.
Accessible
Developer documentation that is human and machine consumable is more palatable to a developer-centric audience which, in turn, helps software technology gain traction within the developer community. This type of traction is one of the many ways a developer community grows and establishes a great reputation.
Machine readability is both associated with the ability for the software to be built in a developer’s IDE, targeting various search engines and multiple devices from desktop browsers to native tablets, mobile devices, and even wearables to effectively consume and display. If documentation is machine-generated, however, but still leaves usability and readability out — a developer scratching their head will quickly abandon the corresponding technology. We see this kind of traction in the overarching need for open source projects to have the least amount of effective documentation that addresses and anticipates the needs of its users.
Writing for the web is radically different than when it first started. Developers favor a less formal tone for a quick TL;DR to digest format. The ability to interact, automatically update, and collaborate is another major change in the way developer content is offered.
The API documentation is no longer a standalone piece of the puzzle. Developer content is driven by empathy for the user.
Developer portals are now supporting initiatives from Engineering fostered through Product Management, Business Development, Marketing, and the greater external Developer Community.
Consumability matters.
Don’t just offer PDFs or tedious delivery mechanisms such as clunky unintuitive authoring tools that produce documentation that a developer cannot easily use on day one of development.
The faster the content helps a developer create working code, the more the developer gets out of the technology.
By making your content more searchable, scalable, and accessible, your documentation will be more appealing to the modern developer.
Editor’s note: We are starting a newsletter at Stoplight with some of the month’s blog posts, our favorite posts from the API community, and more! Sign up below 👇
