Ideas to Improve Software Documentation, Raise Productivity of Mere Mortals

In: best & worst practices|building online products

17 Mar 2014

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.

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 SublimeText or Aptana 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 Bower) 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 no/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. If you see this entry and find it interesting, please get it in front of the right people!

See also

  • Top ten reasons why I won’t use your open source project: “#1 you don’t hav 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
  • 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.
  • 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.

Comment Form

About this blog

I'm CEO of an online/mobile trade publishing firm in the marketing and defense verticals. We strive to make news and data digestible and useful in an environment that is noisier by the day.

This personal blog mixes my thoughts and interests on politics, business, publishing, software, and more. Over the years I have posted items that turned out spectacularly wrong, and a few posts that better stood the test of time.

Categories

Archives

  • chris: thanks, I googled JetBlue interview and your site pulled together a number of excellent articles in [...]
  • Tim Marman: Assuming the market exists, it seems like the biggest challenge here is getting potential customers [...]
  • Konstantinos: ...and one of your first readers from back then (Webvoice anyone?) is here to congratulate you and w [...]
  • Harun Akar: http://abnhost.com just started offering FogBugz hos [...]
  • Sergio Rebelo: "Do you mind hearing some situational irony? I found this entry through a google search." Yes... me [...]