The explosion in the quantity and quality of both commercial APIs and open-source projects is a huge enabler for digital start-ups and small businesses. Instead of painfully rolling your own version of, say, sending email newsletters or displaying a media gallery, in many cases “there’s an app for that.” However, behind the numbers, the very uneven quality of the documentation made available with said APIs, plugins, and packages, is a serious impediment to fully realizing the productivity gains promised by these vibrant ecosystems. (Wow this sounds way too much like an enterprise software whitepaper!)
Typically, documentation takes shortcuts by implying bits of knowledge that the reader may not have, skipping necessary steps, leaving out important nuances, or providing incomplete and obtuse examples. These issues are compounded because of today’s development by integration more than pure coding. I’ve been thinking about how this could be alleviated.
This starts from the very beginning, with many tools failing from the get-go to “Explain Like I’m 5” what they’re about.
The Hive Works Around the Problem
Documentation shortcomings go a long way to explain StackOverflow’s huge success, as many people, confused by syntactic ambiguity, seek clarification from others who’ve been there and done that. Since the SO community has been good at weeding out requests motivated purely by laziness, you end up with a lot of legitimate requests for help. More often than not help will come and the solution appears trivial in retrospect, but trying to understand third-party code through trial/error can quickly become an exercise in frustration.
Fortunately documentation head-scratchers are not just left to go and die on forums. During my daily reading of the list of tech/publishing people I put together on Twitter, I saw Thomas Parisot from the BBC point to their Imager.js library for responsive images. After a quick look I was struck by the high quality of its documentation. When I pointed that out to Thomas, he directed me to a recent entry by Troy Howard – who recently jointly joined Twitter to help them write better doc – and to the Write the Docs conference. This strikes me as very encouraging examples of a community of practice formed to address what I think is a pervasive problem. I’d like to offer another, complementary avenue for improvement.
Solving Software Documentation Doldrums… with Software
Developers, especially amateurs or “semi pros”, usually want to dive right into writing code, and get some form of output out of it as soon as possible. Thus providing full-fledged, well-documented examples strikes me as a key win. What if said examples could work interactively, possibly from within your dev environment of choice? I’d like to offer a half-baked series of ideas for consideration:
- a) Turn examples within your usual static readme.md into the sort of interactive experience featured in this package.json guide (it’s visual so check the link out). In other words, provide code samples informed by the constraints and expectations of their parent package.
- b) Have a universal way for modules and tools to “phone in” their syntax to IDEs so that whatever Grunt task or Jquery plugin you add to your project has the same sort of error detection, function documentation, and autocomplete support already provided for popular languages such as PHP or JavaScript. A sort of meta phpDocumentor, if that makes any sense.
- While we’re at it, merge a) and b), in the form of useful code snippets that get live-documented as soon as you paste them into your code editor of choice.
Some moving parts in the above of course have to be machine-readable for the magic to happen. There’s probably a lot more prior art than I realize, though I bet it’s so far been contained to specific niches, not “the whole ecosystem.” But documentation is an issue that deserves to be addressed at scale.
I envision a workflow where you can go through an (educated) copy/paste/tweak process with a vastly shorter debugging phase thanks to clearer, in-situ hand-holding. Imagine having a live cheatsheet like described above that keeps you “on the reservation”, i.e. within the parameters and syntax accepted by the module you’re using. Having a smart IDE that assists you in writing correct Ruby or JavaScript is of limited help if in the end you spend most of your time re-using and gluing together code already written by others.
At Stake: Efficient Coding for Non-Coders
Modern web development has already redefined how much of a “professional coder” you need to be before you can produce something ready to be used by millions. But there’s still a long way ahead so that you can focus more and more on project/product/people skills, as opposed to knowing how to “talk to the machines.” The easier the development process, the more you can focus on the desired functional output rather than figuring out how to get the computer to spit back what you expect it to.
Next Steps?
Eventually I would love to see the above happen either on Github itself because of its critical mass, or on top of their API (go register gitdocs.io or something!). If a couple leading projects that everybody gets to at least have a look at (say a Bootstrap or React) were to start producing such “live documentation”, then that would help pave the way so that my dreamy Readme.bttr pseudo format eventually becomes a reality.
The Github API has a method to render Markdown (PHP example), and DocumentUp can automatically generate documentation pages/sites from Markdown, so some of the components are already available.
Update after initial post: I pinged Brandon Keepers at Github since he recently committed to their markup project used to render Readme.md files. The fact many projects have very little documentation at all raises interesting “social development” issues about what it takes for a) a project to start attracting attention then b) that attention translating into an interest from the project’s originators, or new contributors for that matter, to improve documentation. It is part of the broader virtuous or vicious circles, with some projects exploding in popularity, adoption, with all the nice network effects, while others just die on the vine.
If anything, that reinforces my belief that a few high-profile projects turning their documentation into an interactive experience could do a lot to shape expectations of what’s possible and desirable.
Updates
September 2021 – Run code samples directly in the Google Cloud documentation.
March 2018 – Microsoft lists all their REST APIs in one place with the ability to make live API calls from the browser. In February they added feedback to their documentation using Github issues. Doc.microsoft.com had been overhauled in June 2016 so this is all part of a long-term improvement process.
August 2017 – Stack Overflow discontinues Documentation. Their rationale: not enough traction in terms of users willing to contribute, they need to focus on making money, and documentation is a pain point but it’s not as bad as Q&A was prior to the creation of StackOverflow.
July 2016 – StackOverflow launches their Documentation hub. They’re one of the best-positioned companies to tackle at scale the challenges I explained above. One of their key areas of focus is code examples, which is exactly what the doctor ordered.
See also: Products
- Postman Echo blends documentation and the ability to make live API calls. The website can launch their desktop application, nice! You can get a whole collection of API calls loaded in Postman in one click from sites that support this. Here’s how to create your own Run in Postman button. Good points here: If A Search For Swagger or OpenAPI Doesn’t Yield Results I Try For A Postman Collection.
- The Jupyter Notebook “is an open-source web application that allows you to create and share documents that contain live code, equations, visualizations and narrative text.” Try it here, you can for instance run R code and see its output right in a “cell” within what looks like a Google Docs page.
- Slate is an API documentation generator that uses Markdown to show code samples right next to their doc. Not dynamic like I outlined above, but definitely a step in the right direction.
- In the meta-SaaS world (SaaS on top of SaaS, which is the norm these days), there’s a whole category including WalkMe, Readme.io, and Inline Manual. Quora thread | Bootstrapped.fm thread. For less complex applications the idea is that the application is the manual.
See also: Examples & Articles
- Top ten reasons why I won’t use your open source project: “#1 you don’t have a friggin’ Readme, #2. You don’t include tests, specs, features, examples”
- tldr: example-based in-situ command line help
- A couple examples of projects that explain well why they have been created and what problem they intend to solve: Lineman,js, Imager.js
- Look at the way Microsoft’s WinJS meshes documentation with embedded code samples that you can edit and live output. That’s what I’m talking about!
- bl.ocks.org displays code output on top of Gist code samples (see bl.ocksplorer.org to easily navigate among d3.js visualization examples).
- For smart autocomplete, see how Tern works with code editors.
- Ultimately coding with live feedback (including on-the-fly relevant documentation) is what’s going to make people more productive. See for instance livecoding.io and work from the amazing Brett Victor.
- Apiary does a good job with “live” documentation: example. But it’s pretty scary that Oracle bought them.
- Contemporary TechDocs.
- Read the Docs – Create, host, and browse documentation.
- Generate awesome docs from Markdown files with Docker and bookdown.io
- 8 Great Examples of Developer Documentation
- API Documentation Can’t [Yet] Document APIs
- Tear down of Stripe’s legendary developer knowledge base
- At a minimum, please use something like the readme-md-generator.