Ideas to Improve Software Documentation, Raise Productivity of Mere Mortals

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 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 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 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.


September 2021Run 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. 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

See also: Examples & Articles

Leave a Reply

Your email address will not be published. Required fields are marked *