The new year promises to be an interesting one for tech. With all the advances sure to take place, however, are companies overlooking the need for good, streamlined documentation? Privacy and data security are becoming more critical, and there’s also augmented reality and blockchain to take up developers' previous time. But we want something far more grounded from the companies that ultimately release these technologies: Please, just improve your documentation! Our plea isn’t specific to one company; everywhere we look, documentation for services, languages, APIs, SDKs, and pretty much everything else needs work. The cold reality is that many developers and engineers just want their code to work. This is especially troublesome when a platform undergoes multiple iterations, which makes keeping track of changes, bugs, and features harder and harder. While some companies provide too little documentation, others offer too much, making it hard to figure out what exactly is going on. A very simple example is routing media for Android. You’d use this feature to stream music from an Android handset to a connected speaker. The concept is simple: app plays sound, you send sound to big speaker because noises are fun. The related documentation, however, is intense. Google has done a very good job of being thorough, but its documentation is plain old-fashioned over-explaining. We’re not saying it should be a simple thing to code (media for mobile is notoriously fussy, regardless of the device or platform), but the approach to building should be different. Apple falls into a similar trap. Not only is its documentation too verbose, a great portion of it remains un-updated; or it’s simply missing, even though it’s referenced elsewhere. The Eclectic Light Company recently examined Apple’s documentation, and has some concerns that those learning to create for iOS or macOS will abandon ship out of frustration:

So what happens when all these young coders are ready to start writing their first proper apps using AppKit? They are going to see this complete void in documentation, the absence of guides, example code, even online ideas, and wonder why they wasted all that time playing with Swift. Not only that, but when they get the hang of something like this in AppKit for macOS, they’ll discover that the iOS equivalent, UIKit, doesn’t support what they have just discovered, and they’ll have to go back to square one if they want to write equivalent code for iOS.

A surprising standout among "good documentarians" is React Native. Its documentation is easy to understand, simple to implement, and fairly thorough. There’s a lot you can’t do with React (such as native music streaming to secondary devices), but given what’s available, its documentation aims to get you up and running straight away, and we like that. [caption id="attachment_185336" align="aligncenter" width="2772"] This documentation is nice and thorough, but it's daunting.[/caption]

Tech Documentation Needs a Reboot

The quiet killer of documentation is Stack Overflow, for precisely the reason we’ve laid out. Developers want code that runs; they could do without an endless explainer of the ins and outs of it all. A search on Stack Overflow for whatever problem you’re encountering typically yields some sort of workable code snippet: Plug it in, run it, and you’re at least one step further than you were before. It’s not always perfect, and you may not have found the perfect solution, but you can clean all that up when you refactor the code (you’re… definitely refactoring, right?). Stack Overflow means that companies need to provide less documentation, at least in theory. In reality, though, it rarely works that way: tech companies treat documentation like a wiki, constantly adding new layers. That's not great for developers who just need a quick, clear answer. While understanding services on a deeper level is obviously critical, most developers favor working code over knowing the finer nuances of a technology. For 2019, a more simplified and contextual approach to documentation would be welcome. We’d rather see a more "choose your own adventure" approach to documentation, focusing on code snippets and troubleshooting or adding features, with the explanations as a background. This approach would help those new to a platform or language, and we think even seasoned pros would rather see this type of documentation. Not only is this more user-friendly, it’s simpler to update as languages change and services become obsolete. It’s something tech companies should already be working on, so we hope we’re just predicting what’s already in the pipeline.