I wrote my first post as a developer about 18 months ago, in April 2018. Since then I have read and wrote a ton of them.

But it hasn’t been a smooth ride.

As developers, these articles are one of the biggest parts of our lives, after StackOverflow, coffee, and pizza.

These articles help us to

1. Learn new stuff for work.
2. Hacking something, and bragging about it.
3. Workarounds or Fixing critical issues.
4. Life lessons, Inspiration and a lot of other stuff…

I spend most of my time doing the first 3 things. We all do. And the hard truth is that we waste a lot of time on them.

Seriously, a lot of time.

This doesn’t mean that the articles are bad. They are just victim of the common problems that most of the developer articles suffer from today.

And yes, it’s the same story with my articles too…

After reading a ton of articles, I found out that there are 4 main problems that most articles face.

Problem #1: The Maintenance Mania

Photo by Zach Vessels on Unsplash

Like everything in this world, articles also have a limited life.

We maintain our cars, homes & laptops to prolong their life. But most of the authors forget this when it comes to their articles.

This problem can occur in multiple forms:

• The article has some code examples that are buggy, since the day they are published.
• The article was considered GOLD when it was published. But with time the code examples don’t work anymore and now the article is referenced by a lot of other articles, and your friends.
  The only thing it does now is to waste peoples time. A lot of time.
• A lot of times, authors don’t respond to the queries and comments of readers who have found a bug in the article.
  And yes, sometimes I am one of them too…

Sometimes, I also miss the comments

But I did clap for him though.

Eventually, these articles turn into debris floating in the vast digital space, damaging authors reputation and readers time.

Problem #2: The Sea Level of Experience

Photo by American Public Power Association on Unsplash

As sea level varies across the globe, the experience level of developers also varies from one developer to another.

We all go through a phase of a developers life when we hoped that we could copy the terminal command like below and it would work.

$ cd myProject

Most of us also copied the $ sign and wondered why I am the only person who has discovered this bug?

This problem intensifies as we go into more detailed tutorials. Due to the length of the articles, it is necessary for us authors to skip the tiny details, that unfortunately, newbies have a hard time figuring out.

Problem #3: Error: Context not defined

Photo by Markus Spiske on Unsplash

We all follow articles differently, using different Operating Systems, different code-editors, different browsers, and whatnot.

This makes it hard for an author to cover all the edge cases in which something might fail.

Even if an author is able to cover all the edge cases today, as the things change frequently, there is a high chance that your code examples will not live long, even after you devoted a lot of time checking all the edge cases.

Problem #4: Articles != Roller Coasters

Photo by 2Photo Pots on Unsplash

Developer tutorials can be lengthy. Painfully lengthy.

As responsible authors, most of us try to make our articles fun and engaging, with all the memes and movie references, some of which make no sense if you haven’t seen the particular movie.

Also, it’s hard to introduce gamification in your articles using the current platforms.

Due to this, a lot the readers, prefer to find the TL;DR saying

Here is the Github repo to containing all the code…

rather than going through the whole article.

Not organizing the content of your tutorials properly leads to a lot of redirection to Github repos. This is good for your GitHub projects, but not for your articles.