I love documenting code and systems. Many don’t. A major argument against documents is that they get outdated as the system evolves. And the faster a system evolves, the faster its documentation gets outdated. Ironically, this is the very type of system which needs the most up-to-date documentation!
An argument is often made, therefore, for self-documenting code. This is ostensibly the kind of code that doesn’t need separate documentation because it is designed and implemented in such a way as to be self-explanatory to the reader.
The twenty-ninth edition of my weekly newsletter “It Depends” is out! Check it out.
This week I talk about self-documenting code. While I don’t think there is a complete replacement for the various forms of documentation of code (design docs, comments, good design, etc), there is a certain underlying principle that I believe allows a codebase to explain both the why of its intent and the how of its execution.
From the internet, Manuel Pais and Matthew Skelton on why monoliths-vs-microservices is the wrong question to ask, a book recommendation on the evolution of computing, and Javier Ramos with a comparison of pulsar and Kafka.
If you like reading about technology and great teams that build technology, you should sign up for the next edition. Bring your friends too! You can read the previous editions in the archive.
I just published the 28th edition of my weekly newsletter. In a public admission of my reluctance to give definitive sounding answers, I have decided to rename the newsletter from “Kislay’s Newsletter” to “It Depends”. Check it out!
In news from the blog (other than the rebranding, of course) I wrote about good/bad collaboration and how we can use good design and product thinking to remove the bad sort.
From the internet, @tastapod proposes CUPID to replace SOLID, Nick Tune on how misaligned incentives fuel organizational dysfunction, @iansmall on how Evernote rewrote their app ground up, and @searls on why PRs are not a very good mechanism for building shared knowledge.
The value of collaboration, talking to your team and your customers is in the brainstorming stage or in the learning phase. This is where we should put together our collective minds, bounce ideas, and figure out the next steps. Once this stage is crossed and we enter the execution phase, collaboration becomes a dangerous overhead.
If multiple teams and people must build something new together, synchronization is inevitable to some extent. However, there is a specific type of low-impact collaboration where people talk to each other to find out what capabilities exist and how to use them. This is seen…
The twenty-seventh edition of my weekly newsletter is out! Check it out!
This week I wrote a brief introduction to the CQRS architecture pattern. I cover what it is and when/why it should/shouldn’t be used, As with all things software, it depends. Caveat Emptor!
From the internet, a curated set of resources on building internal platforms by @asiermarques and @vthot4, an introduction to complexity and complex systems, and a peek into early AWS architectures with @Werner himself.
If you like reading about software engineering, organization design, and the occasional book review, you should definitely visit the archive and sign up for this weekly missive (comes out most weekends). Bring your friends too!
Software systems serve a variety of purposes from their first day, and the requirements on them grow over time. Changing requirements may pertain to a change in business logic, scaling needs, or some other aspects of the system.
To satisfy these often contradictory or overlapping requirements, engineers must make a variety of trade-offs in the design of the system. The problem in making trade-offs is that many of them are not required at the beginning and by the time the need arises, the system design has evolved in such a way that the trade-off cannot be made at all.
The twenty-sixth edition of my weekly newsletter is out! Check it out.
This week from the internet, @adlrocha on tech debt, @jon_moore on switching to an individual contributor role, an analysis of startup innovation by Balaji Srinivasan, and @ruthmalan on architecture principles.
If you like reading about software engineering, organization design, and the occasional book review, you should definitely sign up for the next editions.
See you next week!
The twenty-fifth edition of my weekly newsletter is out! Check it out here.
This week, I wrote a summary of “10% Human” by Alanna Collen. Research into the codependence between humans and the bacteria living in our gut is revealing startling facts, and this book is a good introduction to how our bodies work together with bacteria to make “us”.
This week from the internet, @MarcJBrooker on how web-scale systems are built, Juntin Etheredge on why it takes so long to build software, and Richard Bartlett on why he believes that the problem in organization design is not hierarchies but power structures.
If you like reading about software engineering, organization design, and the occasional book review, you should subscribe to receive the next editions of this newsletter. Check out the archive and sign up!
10% Human: How your body’s microbes hold the key to health and happiness by Alana Collen is my first introduction to the hidden world of the microbes that live in our gut. This topic has been gathering momentum (especially after the Gamechangers documentary) and this book is a great introduction to many to the basic concepts and makes a great case for thinking about our body’s bacterial residents a little more holistically than we have done so far.
The book is well written and engaging. There are a lot of surprising facts and new concepts that I could not help…
The twenty-third edition of my weekly newsletter is out! Check it out!
This week I write about the frequently occurring problem of “go-around” in central products — when teams start building small, custom solutions because the central platform does not expose all its capabilities. This is a pernicious problem of too much abstraction, and platform thinking offers a direct way of addressing it.
From the internet, @tmcw on a fresh start for the internet, a visual introduction to machine learning concepts by @stephaniejyee and @tonyhschu, the Google paper describing Zanzibar (their authorization system), and @acemarke on his experiences in learning and using Typescript.
If you like reading about software engineering, organization design, and the occasional book review, you should subscribe to receive the next editions of this newsletter. Check out the archive and sign up.
Code, products, platforms, books, music