Refactoring

Share this post

Deferring commitment, non-functional work, organizing docs 💡

refactoring.fm

Discover more from Refactoring

Weekly, practical advice on writing great software and working well with humans.
Over 50,000 subscribers
Continue reading
Sign in
💡 Monday Ideas

Deferring commitment, non-functional work, organizing docs 💡

Monday Ideas – Edition #60

Luca Rossi
Jul 17, 2023
19
Share this post

Deferring commitment, non-functional work, organizing docs 💡

refactoring.fm
Share
Article voiceover
1×
0:00
-6:34
Audio playback is not supported on your browser. Please upgrade.

Hey, Luca here! Welcome to the Monday Ideas 💡

Every Monday I will send you an email like this with 3 short ideas about making great software, working with humans, and personal growth.

You will also receive a long-form, original article on Thursday, like the last one:

  • How to Automate Work with Low-code 🔌

To receive all the full articles and support Refactoring, consider subscribing if you haven’t already!

Get full access to Refactoring ✨

p.s. you can learn more about the benefits of the paid plan here.



🐺 QA Wolf

This week I am happy to promote QA Wolf, which has developed a unique, cost-effective approach to testing that gets you to 80% automated end-to-end test coverage in just 4 months — and keeps you there.

How cost-effective? Their latest case study shows how they've helped GUIDEcx save $642k+ / year in QA, engineering, and support costs.

Their secret is a combination of in-house QA experts building your test suite in open-source Microsoft Playwright, unlimited test runs on their 100% parallel testing infrastructure, and 24-hour test maintenance.

Schedule a demo and see for yourself 👇

Learn more about QA Wolf ✨

(p.s. and ask about their 90-day pilot!)


1) 🔮 Defer commitment

A few weeks ago I sat down with James Cowling, former Senior Principal Engineer at Dropbox, and we had a great chat about various topics.

James joined Dropbox when it had less than 100 employees, and saw it grow to more than 2000. One of the biggest challenges in engineering is retaining the ability to move fast and evolve systems when 1) the scale grows, and 2) product assumptions change fast as well.

James’ best advice about this is to keep systems simple.

Simplicity is about optionality. The main quality of simple systems is that they are flexible — you can evolve them in many directions because you haven’t committed to a rigid set of abstractions.

So, whenever you are designing a feature or a system, you should aim to:

  1. Deliver the highest possible value, and

  2. Create the lowest possible commitment

You can think of working on a project as walking in a cone, where the base of the cone is the design space of your final goal. Whenever you create a milestone (James calls them stepping stones), you are moving closer to the goal, but you are also committing to some ideas, thus reducing the possible design space.

Good stepping stones are about making big steps while retaining as much design space as possible.

Type 1 vs Type 2

Another way of framing this is by using Jeff Bezos’ mental model of irreversible (type 1) vs reversible (type 2) decisions. You want to be:

  • Slow and deliberate — with type 1 decisions.

  • Quick and biased for action — with type 2 decisions.

In engineering, complexity is what makes things irreversible — so you want avoid type 1 decisions as much as possible.

You can catch up with the whole chat (video + article) here 👇

Refactoring
How to Plan Software Under Uncertainty 🗺️
Watch now (58 min) | Hey there! A couple of weeks ago I sat down for a chat with James Cowling, CTO at Convex and former Senior Principal Engineer at Dropbox. James’ work at Convex is incredible and I encourage you to check it out, while his track record at Dropbox is equally impressive. There, he led some of the company’s most daunting projects, including designing a multi-exabyte storage system, and later migrating it from AWS to in-house infra…
Read more
3 months ago · 23 likes · Luca Rossi

2) ⏲️ “It should take one day!”

How many times have you heard a PM say that? Maybe replying to your estimate for some work, that looked more like “one week”.

Sometimes it is hard to communicate why it takes so long to build a feature. And the typical reason is that 80% of the work is non-functional.

For any new feature, in fact, you have to:

  • Design for security and accessibility.

  • Add automated tests.

  • Figure out potential bottlenecks at scale.

  • Add monitoring, logging, and general observability.

Then, to favor adoption, there is even more to do:

  • Figuring out how to get the feature to users.

  • Writing documentation (internal and external).

  • Communicating that the new feature exists.

  • Instrumenting the feature with adoption tracking to measure its use.

Even after releasing in production, the work doesn't stop and shifts into maintenance — like fixing bugs and making improvements customers are asking for.

This work only really stops if the feature/product is killed, or the company goes bankrupt!

So, while it may not seem plausible at first, the total lifetime cost of a feature might really be weeks or months of work, even for a simple one.

I wrote a full article about how to balance your engineering investment, and keep your sanity 👇

Refactoring
How to Balance your Engineering Investment ⚖️
Most engineering teams are terrible at prioritization. They talk endlessly about moving fast, being agile, and creating customer value, but do not realize they are shooting themselves in the foot by trying to work on too many things at once. In this newsletter edition we focus on one way this problem can manifest: being stuck in…
Read more
a year ago · 26 likes · Luca Rossi and Lauri Ikonen

3) 📑 Organize docs in Projects and Areas

I am a fan of the PARA method by Tiago Forte for organizing information, and I have brought this to how I organize docs in my teams as well.

I believe, at a high level, you can separate between two major types of notes:

  • 🔨 Project notes — stuff you need to deliver a project. A project is an initiative that has a beginning and an end, and potentially involves multiple areas (cross-functional). Likewise, projects may need a diverse set of docs, including e.g. product requirements, design docs, rollout plans, and more.

  • 🎨 Area notes — long-lived documentation about a specific area. An area is anything for which you need to maintain a standard, and that stays relevant for indefinite time (as opposed to projects, that have an end). Engineering onboarding, database schemas, company org charts are all examples of docs that may not belong to a specific project, but rather to a long-lived area.

Most action happens in project notes, while area notes are more useful for future reference. This separation, though, is not static: after a project is delivered, you may archive most of its material, and move some of it into the respective areas, where it will stay useful for longer.

For example, you may move the database migration specs into the general database docs, or the PRD into the product area.

If your system supports it, you may tag content rather than actually moving it. E.g. I am a fan of using Notion for company docs because it allows you to be flexible with this and define areas and projects through relations and tags, rather than folders. But you can implement this in any system, like Confluence, or Google Docs.

I wrote a full guide on how to write documentation and it’s one of the most popular Refactoring articles ever 👇

Refactoring
How to Write Documentation 📑
Organizing knowledge is one of my obsessions. Today, this is a core part of my work as a writer, but even in my previous life, as a CTO, I invested a lot of energy into processes that enabled good, sustainable docs. I have written many articles about this — but they mostly cover specific angles (e.g…
Read more
4 months ago · 27 likes · Luca Rossi

⬆️ OneSchema — Import CSV data 10x faster

I am a long-time happy user of OneSchema — a ready-made CSV importer for developers, which automatically corrects customer data.

Validate and transform files of up to 4GB in <1 second, customize importer behavior, and launch fast with a library of prebuilt validators.

See how OneSchema works 🔍

We implemented OneSchema in just one day, and what used to be a weakness in our UI is now one of our strengths. — Dominic Kwok, CTO, Heron Data.

OneSchema is also a sponsor of Refactoring 🙏 here is how we run sponsorships transparently.


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. You can learn more about the benefits of the paid plan here.

Get full access to Refactoring ✨

2) ❤️ Share it — 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.

Read with your friends 🍻

I wish you a great week! ☀️

Luca

19
Share this post

Deferring commitment, non-functional work, organizing docs 💡

refactoring.fm
Share
Comments
Top
New
Community

No posts

Ready for more?

© 2023 Refactoring ETS
Privacy ∙ Terms ∙ Collection notice
Start WritingGet the app
Substack is the home for great writing