Online Technical Documentation Is Almost Dead

Anyone who has ever coded before understands that programming involves far more searching and reading than actual coding. I suspect that programmers generally spend 80% of their time online in search of answers, and only 20% of their time on an IDE hammering out code. In fact, a GitHub survey revealed that ‘incomplete and confusing documentation’ is by far, the most encountered problem.

What I find interesting is that programmers don't really talk about this pain point because we think that searching is an inherent part of coding. Most of us have become used to this 80/20 distribution of time and energy between searching/coding, and have accepted that this is just how things work.

I've long pondered about this 80/20 phenomenon, and I believe the root cause stems from the embarrassing state of online technical documentation. In this article, I want to share 5 common problems with technical resources that slow and tire us down.

Common problems with online technical resources

Bloated content

Have you noticed that websites have become increasingly bloated overall in recent years? In the world of SEO (search engine optimization), it is a well-known fact that longer content ranks better on Google. SEO gurus dogmatically encourage content creators to write at least 500 words and embed an image regardless of the topic.

Of course, some topics do warrant a high word count and images, but let's be real - the obsession with word count and images has exponentially increased the amount of bloat of online resources 📈.

This explains why many articles begin with a lengthy backstory of the author or add fluff that doesn't add any value to the readers. The information you're after is usually buried down the page somewhere in the sea of irrelevant content, and it's your job to fish it out.

Here's the real kicker - the fact that you spent so much time on the page sends a misleading signal to Google that the page has insightful content that also deserves to be read by others. By gaming the system, bloated pages now sadly dominate the search results.

Lack of simple examples

The problem with many technical resources is that information is too dense and they don't supplement with minimal examples. This is unfortunate because we typically want to see simple examples demonstrating the usage of a method for example, rather than reading long descriptions of what the method does.

Even if examples are given, they are often unnecessarily complex and only add to the confusion. I've encountered tutorials where the author imports a dataset with a million rows to explain a simple method when he could have just used a dummy dataset with a few rows 🤷.

I believe part of the problem is that technical resources are written by experts who are obviously very familiar with the topic and written for users who have just started. Since there is a substantial knowledge gap between the writer and the reader, the writer often assumes too much from the reader and omits simple examples.

Rarely improved

Most technical resources are published with passion (or by obligation), and soon thereafter forgotten. User feedback isn't incorporated to add polish to the resources. Documentation should be an iterative process of constant refinement, but this is rarely the case.

UI and UX problems

Most technical resources are published without much regard for their look and feel, and this ends up adding stress to the readers. I am personally against:

• showing pop-ups
• polluting 50% of the page estate with ads - especially video ads
• have code snippets in mono-color written with Times New Roman.

Confusing on-site navigation

Programmers are known for preferring the keyboard over the mouse for efficiency gains, but the primary means of finding information on most websites is via clicking. Search is only implemented as an after-thought and oftentimes returns irrelevant results.

Building a platform to host great technical resources

As a strong advocate of clean online resources, I've set out on a journey with a few of my friends to create SkyTowner, a free educational platform that hosts 1900+ docs, recipes, and guides about data science and machine learning. We address all the issues raised above by building SkyTowner based on the following pillars:

• Completely free. The articles are and will forever be free.
• Bite-sized articles. We cut to the chase and directly respond to the question in the first line. No more needless bloat.
• Minimal and simple examples. Expect to find minimal examples followed up with a clear explanation.
• Active maintenance. We routinely revisit our published articles and refine them with reader feedback.
• Great UI and UX. We took the time to really polish up the look and feel of the platform to ensure you have a pleasant experience.
• Powerful Search. The primary mode of navigation searches. Our blazing fast search engine returns relevant bite-sized articles - all without any clicks or page transitions.

Closing thoughts

Do you agree that many online technical resources suffer from the five problems raised in the article? Were there other problems that I missed? I'd love to hear your thoughts!

Also published here.