Newsletter

Writing better documentation, engineering culture, and the subscription economy

Raz TirboacaRaz Tirboaca
Writing better documentation, engineering culture, and the subscription economy

You’re not competing with those who can do, but with those who do

A warm welcome to everyone new here 👋 I’m Raz, a Barcelona based designer, and this is the ‘Makers Weekly’ newsletter. Every week I post resources and notes for tech makers to build better products and services.

Thanks for subscribing, let’s dive in!

TOOLS

✍️ Docusaurus announces that after 4 years of work, 75 alphas and 22 betas, the next generation of Docusaurus is ready for prime time. Docusaurus is a static site generator that helps you ship beautiful documentation websites in no time.

Docusaurus v2 was rebuilt from the ground up with a new modular architecture:

  • React is now also used on the client, enabling a modern Single Page Application navigation
  • Plugins empower the community to contribute useful features as third-party packages
  • Theming is more flexible than ever
  • Docs versioning is now based on snapshot copies, much easier to understand

👑 Peter Ramsey has opened 12 real bank accounts in the UK and logged everything. From the first payment, to freezing the card, to making international payments and customer support. The result is a complete case study on the customer journey and a must-read if you’re in fintech.

🧑‍💻 Improve your web apps’ architecture with Patterns.dev, a free book and online resource on design and component patterns for building powerful apps with vanilla JavaScript and React.

🗣 Amy Hupe explains how to use active voice to write better documentation. In this case study, she’s focusing on design system documentation, nevertheless, the lessons apply to any type of documentation.

What is the active voice?

In the active voice, the sentence’s subject performs the action. For example: “You are reading this newsletter” is active, whereas “This newsletter is being read” is passive.

A huge benefit of using the active voice in documentation is that it removes ambiguity about who needs to do what. Passive statements about things that need to happen are easy to overlook. Instead, we can use the active voice to give clear instructions:

  • Passive: Icons can be used with this button, instead of a text label.
  • Active: You can use an icon with this button, instead of a text label.

🙃 Data visualization is a challenging craft to master as a designer, and sometimes the best learning experience comes from studying the wrong implementations. Bad Visualisations is exactly that, a collection of weird graphics and charts that are useless. Don’t check it out if you love pie charts and are unwilling to change your mind about them, tho :)

👉 Ambiguity effect—the cognitive bias of the week

The ambiguity effect is a cognitive bias where decision-making is affected by a lack of information, or “ambiguity”. The effect implies that people tend to select options for which the probability of a favorable outcome is known, over an option for which the probability of a favorable outcome is unknown.

When buying a house, many people choose a fixed rate mortgage, where the interest rate is set for a specific time frame (typically several years), over a variable rate mortgage, where the interest rate fluctuates with the market, possibly from one month to the next. This is the case even though a variable rate mortgage has statistically been shown to save money.

TEAM

👫 Great engineering cultures are built on social learning communities that enable autonomy without creating silos that prevent cross-team collaboration and learning.

To put it simply, people can share what they know, find what they don’t know, and discover what others know.

🏅 You Got This is a learning hub focused on the core skills you need to improve your working life. Give it a spin, despite its childish design, I’ve found plenty of interesting content there.

MARKET

🎙 Most successful ideas are built off others. Listen to this Nudge podcast episode, featuring Sam Tatam - head of Behavioral Science at Ogilvy, to find out why your great ideas aren’t unique (and why that’s a good thing).

☃️ Coinbase CEO Brian Armstrong warns investors to buckle in for a long crypto winter.

“We all hope it’ll be, you know, 12 to 18 months and a nice recovery, but you obviously have to plan for it being longer than that. And so that’s how we think about it. And we don’t try to get too cute about predicting the future. If we just don’t get distracted, and we keep building great products, we’re going to do fine over the next five or 10 years,” Armstrong said.

Armstrong is right, the best thing we can do in the next 24 months is to keep building!

👋 Uber is ending its free loyalty program, Uber Rewards, so it can turn its attention to its subscription-based Uber One membership. In an email sent to customers, Uber explains that users can still earn points until the end of August and that the last day to redeem points is October 31st.

🔝 Snapchat’s paid subscription, Snapchat Plus, is already a hit with more than a million users in just six weeks. The subscription gives users early and exclusive access to features for $3.99 a month, including changing the app icon and seeing who rewatched your story. In July, the company rolled out ‘Snapchat for Desktop’ to subscribers — the first major feature for paid users.

It’s all about subscriptions!

Thanks for reading! See you again next week 🫶