Anyone who has ever coded before understands that programming involves far more searching and reading than actual coding. I suspect that programmers generally spend of their time online in search of answers, and only of their time on an IDE hammering out code. In fact, a revealed that ‘incomplete and confusing documentation’ is by far, the most encountered problem. 80% 20% GitHub survey 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 , 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. 80/20 phenomenon 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 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. misleading signal to Google 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 , 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: SkyTowner . The articles are and will forever be free. Completely free . We cut to the chase and directly respond to the question in the first line. No more needless bloat. Bite-sized articles . Expect to find minimal examples followed up with a clear explanation. Minimal and simple examples . We routinely revisit our published articles and refine them with reader feedback. Active maintenance . We took the time to really polish up the look and feel of the platform to ensure you have a pleasant experience. Great UI and UX . The primary mode of navigation searches. Our blazing fast search engine returns relevant bite-sized articles - all without any clicks or page transitions. Powerful Search 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

Google

SkyTowner - 1900+ free DS/ML docs, recipes and guide

Too Long; Didn't Read

Boost your HackerNoon story @ $159.99! 🚀

Online Technical Documentation Is Almost Dead

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

10 Benefits of Digital Brochures for Online Business

4 Must-Have Types of Digital Tools for New Solopreneurs

5 Key Benefits of Legal Workflow Automation for Law Firms in 2023

5 reasons to ditch the paper and start document automation

6 Ways Digital Document Management Will Empower Your Business

10 Benefits of Digital Brochures for Online Business

4 Must-Have Types of Digital Tools for New Solopreneurs

5 Key Benefits of Legal Workflow Automation for Law Firms in 2023

5 reasons to ditch the paper and start document automation

6 Ways Digital Document Management Will Empower Your Business

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps