Software, Digital Content, Geopolitics, Economics & More from of a Libertarian Serial Expat and Entrepreneur
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.
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.
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:
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.
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.
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.
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!
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.