Writing 101 for developers | Sandro Maglione

Superpowers are real. Writing is one of them 🧙

It's the fundamental of creative creation. And code is a creative art. If you learn to refine your ideas, communicate your opinion, and share your expertise, you become irreplaceable.

Here are my 101 tips on how I do it 👇

Keep it simple

The friction in writing is all about putting words into the page. No need to make it harder with quirky tools.

We can discuss later about finding ideas, how long to write, when to write, and such. But at the end, writing is just clicking buttons and making letters appear on the screen.

The only extra step I take is styling by using Markdown (MDX).

This newsletter is all a list of ordered mdx files. The magic of turning this into a website should not impede the writing process.

An IDE is a writing tool

I write .mdx files using VSCode. All the same shortcuts I use for code are with me when I write this newsletter.

Some I can't do without:

Ctrl+D: "Add Selection To Next Find Match"
Shift+Alt+ArrowLeft/ArrowRight: Highlight all next/previous word ("cursorWordEndRightSelect")
Shift+Alt+Up/Down: "Copy Line Up/Down"

You can then add any Markdown extension if you want to get fancy.

Here is a fresh screenshot of my VSCode as I am writing this newsletter. Some basic formatting and colors all around MDX.

Ideas journal (and projects)

Don't sit down with the intent of just "Now I write". It never worked, or it takes a long and frustrating time.

Ideas pop up in two occasions:

When you are doing nothing (taking a shower, walking, laying in bed)
When you are deep and excited about a concrete project

If you aim to write consistently, don't allow those ideas to get away (they will, all the time, if you don't write them down).

And work on many side projects, like a lot.

There is a third more rare occasion: when you get feedback from someone who asks you to write about a topic that excites you ✨

This newsletter for example is scheduled every week on Wednesday. I am exploring ideas and projects during the weekend, and I am now sitting here writing on Monday. Two days of review, then release. Every week.

(My) writing guidelines

Here is what I keep in mind when I write:

Straight to the point
Short paragraphs
Interesting is more important than elegant
Make it shorter
No long, complicate, mouthful words
Few adverbs

"General" writing advices are overrated. Just like in tech, "it depends" it's always the right answer 🙌

Bonus: remember you are a developer

The actual "practice" is just sheer writing. But don't forget the magic of code.

I have a full setup to take a bunch of mdx, churn them, inspect them, do all shorts of tricks, and export a static site. Everything that comes in between words and the final build is in your control 🏗️

export class Mdx extends Context.Tag("Mdx")<
  Mdx,
  Effect.Effect.Success<typeof make>
>() {
  static readonly Live = Layer.effect(this, make).pipe(
    Layer.provide(
      Layer.mergeAll(
        ShikiPlugin.ShikiPlugin.Live,
        HeadingsPlugin.HeadingsPlugin.Live,
      ),
    ),
  );
}