The pyramid principle, markdown diagrams, and removing friction 💡

Monday Ideas — Edition #98

🔳 Unblocked • talk to your codebase

I love using surveys to find ways to improve developer experience.

We have just ran our own, about engineering productivity, and I remember going through Stack Overflow’s developer survey last year.

A key figure in there was that >60% developers spend between 30 and 120 minutes every workday searching for answers, often about their own workspace and code.

This is an area where AI can be truly distruptive, which is why I am happy to promote the fantastic work done by the guys at Unblocked 👇

Unblocked provides helpful and accurate answers tailored to your team, application, and processes by complementing your source code with discussions in GitHub, Slack, Confluence and more.

---

1) 🔺 The Pyramid Principle

A couple of weeks ago we interviewed Wes Kao about what good communication looks like, especially for engineers.

Wes shared a lot of fantastic advice, and one in particular stuck with me: communicate your main point first, and present the rationale later.

This reminded me of The Pyramid Principle, by Barbara Minto.

For Minto, you should present ideas in a way that captures the recipient’s attention, to increase the chances they understand them. So, each idea should be organized into four sections:

1. Situation — the context, or the status quo. E.g. we need to deliver the product in six months.

2. Complication — a change or a problem in the current situation which makes this communication necessary. E.g. current requirements are unclear.

3. Question — the main problem statement. E.g. we want to agree with you on the process to minimize risks and deliver the best possible solution over these six months.

4. Answer — your best answer to the posed question, or the process to put in place to get such answer. E.g. we define a core subset of the design to be delivered in 4 months, while keeping 2 months of buffer for learnings, improvements, and setbacks. We will ship working software every week and keep stakeholders posted so we can steer the development fast if we realize we are going in the wrong direction.

At this point, you typically need to support your proposed answer with arguments and ideas. Such ideas should form a pyramid under a single thought, which is the answer you propose.

The SCQA + Pyramid Principle, summarized.

Below that, you should summarize and group the next level of supporting arguments. So, the Pyramid Principle is based on three key concepts:

1. Start with the answer first — most people think better in a top-down fashion. Start with the answer and present supporting ideas later.

2. Summarize and group supporting arguments — force yourself to limit the number of arguments you propose, by grouping them and focusing on the main ones. Follow the Rule of Three.

3. Logically order your supporting ideas — make sure that the ideas you bring together under each group actually belong together, are at the same level of importance, and follow some logical structure.

More ideas and examples on how to improve your communication skills 👇

How to Improve your Communication 📣

---

2) ✏️ Diagramming in Markdown

Earlier this year I discovered Mermaid, an open-source diagramming tool that uses Markdown to create and modify complex diagrams dynamically.

As you may have figured out by now, I am a visual person, and I have probably created hundreds of diagrams in my life. Well, diagrams are always a mess to manage at a team level: you move around those jpegs, lose track of the source, get fixated with style, and more.

Mermaid’s code-first approach fixes most of these issues. In fact, you can now version diagrams just like you do with code, and update them easily. You can also define themes globally, so you keep your focus on content, and save a ton of time.

Mermaid is almost universally loved and has an incredible number of integrations, my favorite being those with Github and Notion: you paste Mermaid code, and get the diagram automatically displayed!

I covered more ideas and techniques you may adopt this year in our 2024 tech radar 👇

New Tools and Techniques for 2024 📡

---

3) 🏋️‍♀️ Stick with habits by removing friction

Any activity always includes winning some friction that is not related to the activity itself:

• To work out at the gym, you have to first change clothes and drive to the gym.

• To eat healthy, you need to spend time prepping your meals.

The more you can reduce such friction, the higher the chances that you will keep performing the habit. In other words, for anything you want to do, you should find the path of least resistance.

For me, one of the tactics that work best for this is by setting dedicated environments that are as turnkey as possible.

For example, I have always struggled at going to the gym, so I have set up a small one at our place. We are lucky to have a spare room we can use, so we bought some equipment and a hard rubber floor. We also keep gym clothes there, so basically everything-gym happens in that room, and friction is close to zero.

Our home gym. The rubber floor makes a big psychological difference. Before that, it was just a room with some stuff in it.

Result: both my wife and myself are now working out more than we ever did.

I also find that, contrary to common sense, buying nice stuff helps to kickstart a habit. We didn’t need the good rubber floor to start working out, or a big mirror, but we bought them anyway. Now the room truly looks like a gym, it feels professional, which has an impact on our identities. We feel like we are “people who train at home” and are serious about it.

I used to poke fun at folks who start side projects by buying the domain name. Well, not anymore. These things matter — they can change the perception you have about that activity, and about yourself.

I learned a lot about this by reading Atomic Habits, by James Clear, in the community book club. I also wrote my summary + review a few months ago in the newsletter 👇

Atomic Habits 📙

---

And that’s it for today! If you are finding this newsletter valuable, consider doing any of these:

1) ✉️ Subscribe to the newsletter — if you aren’t already, consider becoming a paid subscriber. 1500+ engineers and managers have joined already! Learn more about the benefits of the paid plan here.

2) 🍻 Read with your friends — Refactoring lives thanks to word of mouth. Share the article with your with someone who would like it, and get a free membership through the new referral program.

I wish you a great week! ☀️

Luca