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.
A sense of urgency in shipping features is probably the worst result of the agile mindset. While it makes some sense in absolute early-stage startups where everything has to be built ground up, but in places that have a little bit of stability, this is a vestigial mindset which causes a lot of problems.
Delivering the right kind of product is a three step process.
I just published the 33rd edition of my weekly newsletter “It Depends”. Check it out!
My handpicked best of the internet this week — how @ApacheFlink handles backpressure, Start with why by @simonsinek, the “pace layer” model for understanding layers in complex systems by @stewartbrand, and the internal design of @SnowflakeDB
If you like reading about technology and great teams that build technology, sign up for the next edition and bring your friends! You can check out the previous editions in the archive.
The 32nd edition of my weekly newsletter “It Depends” is out! Check it out!
From the blog, my take on why developers don’t write documentation. There are many difficulties to it (tools, time, priorities, maintenance, etc.), but the elephant in the room that few developers are willing to acknowledge — writing is thinking, and thinking is hard. Check it out and let me know what you think.
From the internet, the drama between Linux commnity and University of Minnesotta, Justin Jaffray on push versus pull query engines, and a fantastic visualization of how Kafka works.
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 check out the previous editions in the archive.
I have been writing about documenting code of late, so of course, my Medium recommendations threw out an article about “the real reason why developers don’t write documentation”. The article claims that the lack of good tools for writing is the biggest culprit in discouraging software engineers from documenting their work and decisions.
I usually don’t pick on specific articles, but this one triggered the hell out of me. The writer makes some okay points about diagramming tools, but the overall piece is so misleading that it obfuscates this important issue. …
The 31st edition of my weekly newsletter “It Depends” is out! Check it out — https://kislayverma.com/newsletter-archive/?email_id=55
This week I talk about the second law of building software platforms — External Programmability. This principle is as critical to building true platforms as it is conspicuously missing from many of the so-called “platforms” we come across. Any system can be modified from within. Platforms should be modifiable from the outside.
From the internet, @mikiobraun on large-scale software engineering is still difficult, how Postman handles millions of concurrent connections, and a look at the attack on academic integrity by Big Cos of all sorts.
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 check out the previous editions in the archive — https://kislayverma.com/newsletter-archive/
We should not have to modify central systems/platforms to achieve variant behaviours for different use cases. We should be able to plug in these behaviours from the outside to customize specific parts of the overall system behaviour. This will make our system more durable by offering a powerful mix of capability and customizability.
Imagine you are building a central system that is intended to be used by multiple other teams. Depending on the kind of complexity offered by the system, one or more clients may ask for variations of the original behaviour specific to their use-cases. …
The thirtieth edition of my weekly newsletter “It Depends” is out! Check it out here!
This week I talk about making the “QA signoff” more agile. The testing world hasn’t kept up with agilification of the software development process, and the old end-end testing mindset is still the default in many organizations. I explain a more modern approach (not uncommon among the leading tech companies) which can help us keep the delivery pipeline running
From the internet, Martin Fowler on outcome versus output, a book review that explains why we don’t have flying cars yet, and Wix engineering team on reducing latencies.
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 check out the previous editions in the archive.
End-to-end testing refers to the approach of testing every step of every single user flow. e.g. In the e-commerce domain, this might mean testing every API call and database write/read from the moment an order is placed to the moment it is delivered. The end-to-end testing process will validate every notification sent to the customer, every tool used by the ground force, and every third-party interaction involved. This testing paradigm validates the end-user experience by validating behaviour across multiple domain boundaries and teams.
Back when all systems were monolithic, development batch-y, and releases infrequent, this was the de-facto approach for…
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.
Code, products, platforms, books, music