What I learned about writing technical articles on the web

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 🚀

Sandro Maglione

@SandroMaglione

·Follow

Working on an @EffectTS_ getting started step by step course 👇 Starting from the real basics and going into the details of each step This is you chance to suggest topics, questions, projects you would be interested in Go 👇

10:55 AM · Jul 8, 2024

Read 4 replies