About the hesitancy in reading Software Engineering writings
Over my university years, I’ve noticed that my peers don’t have a keen on reading technological writings, i.e. tech documentations, or articles on a tech topic. They prefer watching videos or, somewhat unfortunately, read articles that are “easy to understand” but lack the credibility or depth, usually from incompetent writers (I’ll show you some).
There is nothing wrong with how you perceive information, but if you are so determined on not reading the documentation for a piece of software from its creators, I can confidently tell you that you are doing things fundamentally wrong. How wrong, you ask?
An example of skipping documentations#
Granted, some documentations are just utterly awful (I’m looking at you, Java documentation). But let’s look at a proper, manly documentation.
NOTE: A technical writing on a specific topic that is referenced by the maintainers of the software could be considered a documentation. Examples can be the Next.js’ documentation.
You want to learn Node.js. One-liner: Node.js is the thing that runs JavaScript outside of the browser, and you want to learn Node.js to write backends with JavaScript. So you look for a tutorial.
Let’s hit YouTube, the default source of graduates’ knowledge. Here’s one:
“8 hours!?” says a graduate. They proceed anyway. How many of you actually went through an 8-hour tutorial and feels superior afterwards?
Here’s how I would do it. I go to Google and search for Node.js, and click the
official Node.js website, nodejs.org
. I click Docs, then Guides, and
then Getting Started Guide. Just one more step, I click Introduction to
Node.js highlighted in green color.
Here I am, the link that’s recommended by the Node.js officials, Introduction to Node.js:
As a newcomer, not only this page tells me what is Node.js, it also instructs me about what I need to know before learning Node.js. The Getting Started section does exactly what it implies: Getting Started.
Take the page The Node.js fs module for example, which is the “File System” module. It is as concise as it is possible. I’m sure you can read this in 5 minutes. Not only the YouTube version 3 times lengthier, if you need to review something, you might be lost rewinding the video to a very specific timestamp instead of just scrolling by maybe half a page.
If you value your time, then I think I have to persuade you no more.
“I can NOT focus when reading!”#
That’s totally fine! I could say this much to you: There are incredible sources from ingenious people in your subject of interest that are only available through books or writings of some sort. The choice is yours.
Here’s what’s needed for an article to be “engaging” (for me):
- The article must be exactly what I seek.
- The article must be in good format. No unnecessary wordings to waste my time.
- I know everything that the article presents but doesn’t explain.
- The article must lead me somewhere. I must be able to guess things ahead of time.
- Skim-able.
Before you go, I have some not-the-best-quality writings that I want to show you, so you’d know what kind of writings to avoid.
Bad Writing Examples: “Backend Development Is Not Hard”#
This article was on daily.dev one day. I had skimmed through it.
TL;DR: A short “What is a web server?” section, followed by a tutorial on installing Node.js, Express.js and run an HTTP server.
Is this whole article justifies the “Backend Development Is Not Hard” statement in the title? I’ll get straight into the weeds: Backend Development is hard. Doubt? Go on and do backend for a month, maybe two, then evaluate your knowledge with the Backend Roadmap.
Does a doctor say, “Being doctor is easy feet”?
You get the point. Nothing is easy, and if someone tells you otherwise, they are trying to sell you something.
If I were a backend newbie, and I want to use JavaScript, I would do the Node.js
Getting Started, then trying to create a backend immediately. Maybe I need a
database, or need a config file, or async
, or maybe Load Balancing, but until
I need those, I don’t care, and no one will try to teach me things I don’t
care yet.
Bad Writing Examples: “Git branching for small teams”#
This is an article in the “Top” page of dev.to
. “Elite”, you might say.
One question only: Do you really need to branch?
If you can’t answer this question (or the article doesn’t say, as in the article above), you should not read this article at all, or any “Git branching guide”. Here’s why you don’t branch (mostly), if you are interested. It’s like learning how to fly a plane without knowing why you need to do so.
This article doesn’t explain the situations when you might need to branch. Don’t assume you always branch. Additionally, I don’t think I will read this anytime soon. I consider this article “misleading”, especially for newcomers.
If you have no idea why you’re reading the thing, don’t.
Bad Writing Examples: Step-by-step coding articles#
Didn’t come up with any particular example. But there are some identifying features:
- A big wall of code.
- Doesn’t explain everything. Yeah, I need everything in a coding article to be explained, or at least self-explanatory.
- Heavily, but badly opinionated.
- Use of external packages that are not essential.
It takes skills to read these kind of articles, otherwise it has big consequences. If you can’t identify good coding, close the tab and stick to the basic.
Hope you will find some good articles to read soon. Here’s one I’ve read today: HTTP/3 From A To Z: Core Concepts