441 reads

How to Write Better Posts as a Developer.

by Vaibhav SainiAugust 16th, 2019

Too Long; Didn't Read

Vibhavsaini is a co-founder of @tbc_inc, an MIT CIC incubated startup. He wrote his first post as a developer about 18 months ago, on April 2018. He has read and wrote a ton of articles about Web 3.0. He found out that there are 4 main problems that most articles face: Maintenance Mania, Sea Level of Experience, Error: Context not defined, Short Distribution of the audience, and Difficulty Difficulty of understanding the content of your tutorial.

People Mentioned

featured image - How to Write Better Posts as a Developer.

I wrote my first post as a developer about 18 months ago, on 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

Learn new stuff for work.
Hacking something, and bragging about it.
Workarounds or Fixing critical issues.
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

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 people's 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…

But I did clap for him though.

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

Problem #2: The Sea Level of Experience

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 developer's life when we hoped that we could copy the terminal command like below and it would work.

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

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

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 repository containing all the code…

rather than going through the whole article.

Not organising the content of your tutorial properly leads to a lot of redirection to Github repositories. This is good for your GitHub projects, but not for your articles.

By the way, as I mostly write about Web 3.0, all these above problems just get worse for me.

As Web 3.0 is a new community, the things break frequently, making my articles even more short-lived. There is a lot of uneven distribution of the audience when it comes to experience. The learning curve of Web 3.0 makes this even worse.

The significance of context matters more than ever here, as most of the libraries are selectively supported for a few OS/browsers.

And when you think your problems are over, the length of the article becomes so long (due to the learning curve and setting up the requirements) that it’s even hard for me to read it in one go, let alone my audience.

I tried to find something that may help me tackle these problems. But no luck.

So, when I started SimpleAsWater to make development & learning easier on Web 3.0, I pledged to also build a story-telling platform that is focused on the needs of the developers.

We are going to start a private BETA testing for our developer-centric storytelling platform in the coming weeks. You can apply to be our first 100 people who will test out the platform.

Register for BETA Testing — SimpleAsWater

Meanwhile, Let me show you a few sneak-peeks of what we are building.

Solution #1: Applying CI/CD to your Articles

CI/CD is the De facto standard in software development when comes to code maintenance. For us developers, code examples are one of the most important parts of the article. Then why not do CI/CD for your articles?

This seems really complex. But we are here to make it simple.

We do regular CI tests on your code examples to make sure that they are still alive. If we find something fishy, we will mail you with the details of what is broken.

This makes it simple for everyone to maintain your articles.

Solution #2: How about asking for help from others?

Today, if we are stuck somewhere while reading an article, we usually drop a comment asking for some help. Your comment can easily get lost in the multitude of “thank you” comments.

So, we are introducing a “help” comment which will be highlighted to every reader who is reading the same section of the article. This, way your doubts can be discovered easily.

When the doubt is solved, the help comment and the chosen answer are recorded. Whenever someone is asking for help in the same section, he/she can be shown the previous “help” comments, that can be similar to what he/she wants to ask.

Solution #3: Articles = Git repositories

Most of the articles don’t stay active for a long time. So does your un-tracked code.

We treat your articles as public git repositories, where people can add issues and submit PR(s).

Sounds complex? Don’t worry, it’s all going to be under the hood.

This will help authors to engage more easily with the audience and provides the audience with an ability to help the author to maintain their articles.

Plus it makes it easy for us to do CI/CD of your articles.

Solution #4: Defining a Context

Rather than everyone following a different path(using a different OS, browsers to run code), we try to put everyone on the same page.

We do this by providing an in-built code-editor. Basically, you can embed a live VS Code editor in your articles, where everyone can try out the same code in the same environment.

Solution #5: In-built Gamification & Entertainment Support

One of the biggest parts of making your content engaging and fun is organising & displaying your content in a good way.

So, apart from adding support for built-in memes, we are providing what we call “Steppers”.

Here are a few examples of how they look.

Using “Steppers” you cannot only organise your content but also choose to lock the parts of an article which will be unlocked only if you complete a specific part.

You can also add an option for passing a step in case someone is just interested in a specific part of your tutorial.