What I learned about writing technical articles on the web

Sandro Maglione

Sandro Maglione

Web development

Writing tech tutorials is a soul-searching experience ๐Ÿ‘€

You throw away all your assumptions to write with a beginner mindset.

I have been writing tech stuff for quite some time now (5+ years indeed ๐Ÿ˜ฎ).

Here is what I learned ๐Ÿ‘‡


Curse of knowledge

Ever heard about a thing called "Curse of knowledge"?

[...] when an individual (unconsciously) assumes that others have information that is only available to themselves, assuming they all share a background and understanding

Simply put: I tell you something assuming you have all the prerequisite knowledge to follow me step by step, when in reality you are missing the context entirely.

In practice I can make the best "step-by-step tutorial" or "beginner guide", but if I miss the correct definition of "initial step" or what "beginner" means, then nothing will connect.

Lesson: clearly define your target audience and required prerequisites, then periodically check your assumptions based on the target audience

Levels of depth

Here is some code, how much can you understand here?

import { Effect, Console } from "effect";
 
const main = Effect.succeed("Hello World")
  .pipe(
    Effect.flatMap(Console.log),
    Effect.runSync
  );

How about this?

import { Effect, Console } from "effect";
 
const main = Effect.succeed("Hello World")
  .pipe(
    Effect.flatMap((message) => Console.log(message)),
    Effect.runSync
  );

Let's expand even more:

import { Effect, Console } from "effect";
 
const main = Effect.flatMap(
  Effect.succeed("Hello World"),
  (message) => Console.log(message)
).pipe(Effect.runSync);

All the way to:

import { Effect, Console } from "effect";
 
const main = Effect.runSync(
  Effect.flatMap(
    Effect.succeed("Hello World"),
    (message) => Console.log(message)
  )
);

All the above have the same exact result.

While you may go with the most "elegant" code in your codebase, the same cannot be said when you are writing a tutorial on it.

The level of "easy" changes as you learn more, but that's not the same for people who just started

This requires to deeply question your assumptions and go in the details of "why" and not only "how":

import { Effect, Console } from "effect";
 
///           ๐Ÿ‘‡ `runSync` executes an `Effect` synchronously
const main = Effect.runSync(
 
  /// 2๏ธโƒฃ Use `flatMap` to extract the success value
  /// from an `Effect` (without executing it)
  Effect.flatMap(
 
    /// 1๏ธโƒฃ Wrap the string "Hello World" in
    /// an `Effect` that always succeeds
    Effect.succeed("Hello World"),
 
    /// 3๏ธโƒฃ The second parameter of `flatMap` is a function
    /// that gives us access to the value inside `Effect`
    ///
    /// Here you return another `Effect`
    /// (Note: `Console.log` returns `Effect<void>`)
    (message) => Console.log(message)
  )
);

See? Even 3/4 lines of code can hide an overwhelming amount of details (aka assumptions ๐Ÿ’๐Ÿผโ€โ™‚๏ธ).

Write about it while fresh

The above problems could be solved (partially) if you document something as soon as you learned it.

I also like the excitement of sharing an awesome new feature or pattern right after I discover it ๐Ÿš€

Right after you learn something you sit in that sweet spot between two "you":

  • You clearly remember your older "you" struggling to understand an idea
  • You clearly feel your new "you" that just solved the puzzle

This is where the magic happens: you know how to connect with your previous self (and all the people just like you before you learned that new idea).

Why not many people write about tech

Here are my thoughts:

  • It's more exciting to implement a new feature than writing how you developed an older one
  • Technical writing requires you to know something before the writing begins. However, if you already know something, you either consider it trivial or you are not interested in writing about such "basic" concepts
  • You don't believe you have something interesting to write about
  • You don't think that anyone would be interested, no one would read it, so no point in writing it anyway

Here is what I can tell you instead:

  • The writing process is all for yourself: it's the process of collecting random ideas and giving them order
  • You can avoid reinventing the wheel: the tutorials you write will be gold for yourself in the future to remember how you implemented a feature in the past
  • Connect with people: no matter how niche your content is, someone out there found value in what you wrote, and that's awesome. You can then connect directly with these people

I am launching a new course

Speaking of writing: I am launching something new next week ๐Ÿš€

I am committed in writing and sharing more about everything that I learned as a software engineer.

Expect something great and extensive coming in the next months (stay tuned ๐Ÿค)

If you or your team is interested in a more 1-1 customized training from me, feel free to respond to this email to connect and have a chat with me ๐Ÿ‘‹


Conclusion: more people (you included) should start writing more.

Imagine a world of niche blog posts, each writing about a small use case that happens to be exactly what you needed! That would be awesome ๐Ÿš€

See you next ๐Ÿ‘‹

Start here.

Every week I build a new open source project, with a new language or library, and teach you how I did it, what I learned, and how you can do the same. Join me and other 700+ readers.