Developer documentation: How to get it right
If you're building developer-facing tools and services, then there's one thing you shouldn't forget: the documentation.
If that's missing, no matter how many use cases your service supports, or how comprehensive you've made your APIs, or even how attractive the offers in your pricing plans, you won't get any users.
Getting documentation right isn't easy. There's a lot to be considered when putting it together, and modern developers are a lot more demanding than they used to be: after all, your documentation has to be better than the peer support they get on sites like Stack Overflow. The days when Microsoft could own developer mindshare through its MSDN CD-ROMs are long gone, and now your documentation needs to be a living part of your product.
Much of the state-of-the-art in developer documentation today builds on those MSDN discs, providing details of what code should do, and samples of how to use it. But technology has moved on, and we're now able to do a lot more with our documentation.
One option is the use of code playgrounds, taking the idea of the REPL, the read-evaluate-print-loop, and using it to embed live coding environments into our documentation tools. Apple's Swift playgrounds are one example of this approach, letting you try out code on an iPad, learning a new language and exploring its features. Similarly, Xamarin's Live Player takes code from Visual Studio and runs it on a device so you can try out new features.
As REPL systems become easier to implement in JavaScript, they're moving into web-based documentation platforms, letting you try out code samples and tweak them using web-based editors before using the code in your own applications. A good example of this is the R documentation, which includes sample data sets and visualizations, so you can see how R's statistical tools can be used, and how different visualizations work with data sets.
The use of REPL-based tooling is a significant advance over the old pure text-based documentation found on CDs or on the web. Interactive coding environments can even be enhanced with debugging tools to show just how code works, and why it does it what it does. They're also the foundation for interactive tutorials that can take you through code step-by-step -- bringing documentation and the online course closer together. An interesting, if not quite complete, example is Microsoft's recently launched AI School, which wraps several different sources into one learning platform for all its Azure machine learning services.
The same underlying approach can deliver dynamic documentation that responds to your needs, avoiding information you don't need. Cloud services are using these techniques, with authentication provider Okta's new developer site displaying content tailored to the API features you need for your application. By reducing the amount of extraneous information, the intention is to reduce the risks associated with using the wrong options in a call -- reducing errors and minimizing the load on the service.
There's a strong argument, too, that documentation needs to be open to anyone to work with; building on the Wikipedia model but adding in the source control approach of services like Github. Where Wikipedia lets anyone edit live content, Github requires a pull request to merge in changes. That way editors can proof-read content, and developers can check and test sample code before it's published. Even so, it's still an open process; anyone can see the current development branches for the documentation, allowing collaborative editing and peer review.
Github's own Markdown text formatting tools simplify this approach, making it easy to quickly format descriptive text. Simple tags work with text that's edited in familiar programmer's file editors like Visual Studio Code and Github's own Atom, so that documentation can be developed in the same tool as code. That approach lets code formatting tools in the latest generation of documentation engines take the style tooling from those same editors and use it to display code in a familiar and readable fashion.
Documentation developed this way can be part of your build process. Twilio won't publish a new API, or an API update, without corresponding documentation, with tests as part of its continuous integration platform that ensure all calls are described with sample code. If documentation isn't present, then code won't be deployed. Ensuring that code and documentation are part and parcel of the same deliverable is important, but it's also the start of an ongoing process, where documentation expands to support users as part of a collaboration that goes beyond the scope of most DevOps processes.
With documentation tooling that's based on the tools used to write code and documentation processes based on the same processes used to write the same code, it's not surprising that documentation can now be opened out to the whole world, with contributions from inside and outside development teams. The ideal documentation is written by the same developer who wrote the feature, edited and published collaboratively, and debugged and kept up to date by users.
Microsoft is taking this approach with its new Docs service, which interestingly also is the part of the organization that contains its new Cloud Developer Advocates, many of whom come from open source backgrounds. Perhaps this is the next stage of a modern documentation program, a team that can both create that documentation and present it on stage. The relationship between code and documentation is key, and if Microsoft can take its developer advocates to where the developers are, it gives it an advantage in both understanding developer needs and responding to them.
Delivering effective documentation is essential to success for any service or platform. Developers can't go to a bookshop and pick up a programming manual, when the code they're working with changes far faster than a book can be printed. If you're not building a modern documentation platform, then you're going to be left far behind in the race for developer mindshare.
Recent and related coverage
Low code development: Is this the future of enterprise apps?
Low code promises to streamline the development of business applications. Appian CEO Matt Calkins explains why.
Software developers and designers risk over-automating enterprises
Noted software design advocate and author says automation is taking away valuable human judgment. The goal of good software should be to amplify, not replace, human work.
Open source's big weak spot? Flawed libraries lurking in key apps
To avoid becoming the next Equifax, it could be a good idea to scan your apps for vulnerable open-source libraries.
Read more developer stories
- Google's mysterious Fuchsia OS gets Apple Swift language support
- GitHub to devs: Now you'll get security alerts on flaws in popular software libraries
- Google's Angular, Apple's Swift: Meet the decade's fastest-growing developer tech
- These Ukraine veterans fought Russia: Now they're being turned into software devs
- Snapchat gets Android developer religion -- better late than never
- How Salesforce is using low-code orchestration to save 'floundering IoT projects'
- Amazon launches Cloud9 developer environment for writing, running, debugging code in browser (TechRepublic)