Rahul gives unsolicited advice

On Friday, Arun and I talked mostly about two things - documentation and processes. Arun is working on documentation and he was wondering whether or not he should document the failure modes of an external tool that is used as part of a process. This gave way to a broader discussion on what should be documented and when. In this particular instance, I talked about how documenting the failures of an external tool internally feels unnecessary unless the external tool has no documentation to speak of. There can be a basic expectation from the developer that they can look up the tools' documentation if and when necessary. In general, we talked about deciding whether or not to document something depending on how much time it can save a person/company. If it can save a person one or more hours per week, the savings can add up to thousands of dollars per years. If the documentation can only save a few hours an year, then it might not be worth spending time working on that piece of document...

Words aren't always enough. I was trying to digest the  Keycloak documentation on securing applications  and after spending eight hours on that page, I finally realized that I was trying to construct diagrams in my head using the words. I was trying to construct the control flow in my head using the words on that page. And that is almost always a lossy transmission of information. I believe that a few sequence diagrams ( uml , mermaid ) can do wonders in that documentation, helping both people who need words and those who need images. And the verbal people can communicate with the visual people using the images and the text! There's a dearth of diagrams in software project documentation. You could respond by telling me that most software projects don't even have documentation so expecting diagrams is a stretch. To that, I say that accepting diagrams as documentation might help address the issue. Contributors might not implicitly know that diagrams are acceptable contributio...

At some point in November of 2019, I asked a work colleague to be my mentor. He is a CPython core contributor, he has been at Enthought for over a decade and I wanted to learn from him. I don't exactly remember why but we decided that we would start reading a book and discuss it every week. My broad goal was to get better at writing software, which is why I think we chose to read and discuss the book  Clean Architecture by Robert Martin . For those of you who don't know, it's one of the classic texts on software and software architecture. Initially, it was supposed to be just the two of us but others in the office were interested in the book as well so there were three of us when we first met to discuss the book on the 22nd of Nov 2019. We added one more person when we met a week later. I think we discussed a few chapters every week, depending on how big the chapters were or how interesting we felt they were. We didn't have a fixed deadline to finish the book so there w...

In a previous post , I wrote about 8 things a government can do about FOSS where I talked about categorizing the governments actions in 8 distinct ways. From what I've been reading online, it looks like the Indian Government is already trying to Do-It-Yourself (DIY) FOSS. To recap, DIY-ing is the very last option in the "8 things" and it's risky. Especially in the case of FOSS, DIY is risky. Given the scale of government operations, any DIY solution that the government comes up with gain widespread usage, which can then lead to inertia. Remember that DIY-ing requires not just building expertise in FOSS but also continually maintaining it. If the Indian government doesn't maintain the necessary expertise, it risks the FOSS project falling behind the curve. Let's look at the Samarth eGov project as an example of the Indian government DIY-ing FOSS. Samarth project aims at creating an Open Source, Open Standard enabled Robust, Secure, Scalable and Evolutionary Pr...

If you write software, you need to start maintaining Architecture Decision Records (ADRs). ADRs roughly fall into the category of Developer Documentation. They aren't aimed at the Users of the software. Instead, they are aimed at the developers and maintainers of the software. They usually contain information about the layout of the package and what the code does. ADRs, in this context, are an absolute necessity. By definition, ADRs are simply a Record of a Decision that has an impact of the Architecture of the application. In fact, Any meaningful technical decision made in a software project, irrespective of whether it has an impact on the architecture of the application, needs to be documented. I first came across ADRs in Chapter 17 of Fundamentals of Software Architecture book. A few of us (at Enthought ) read this book earlier in the year and ADRs are one of the things that we took away from the book. You can find more information on ADRs here and here . Here's what the f...

The Takshashila Institution taught us last weekend that the various types of government action can be roughly split into 8 categories. Let's look at the categories in the context of Free and Open Source Software (FOSS). Do Nothing The government can choose to do nothing about FOSS and leave it up to the various public and private entities to decide what each of them want to do with FOSS i.e. whether or not they want to integrate FOSS into their IT systems, how deeply integrated FOSS is in their IT systems, etc. For example, most big public and private players have Enterprise Resource Planning (ERP) software as part of their IT operations. And when deciding an ERP software to use, they can either choose to go with a provider like Oracle ERP , which isn't FOSS, or they can choose to go with a provider like ERPNext , which is FOSS and home-grown in India. It might sound like doing nothing would mean the government doesn't incur any costs. Alas, that isn't really the case....

I keep rewatching this talk by Randall Koutnik on Developer Career Path every so often, just to reevaluate my own developer career. I think the "Solution Implementer", "Problem Solver", "Problem Finder" career path that Randall talks about makes a lot of sense, especially in the career path I am currently on. A highlight of his talk is the discussion around shapes and sizes of problems and that the developer career path should ideally expose the developer to a large number of shapes and progressively increasing sizes of problems. Thinking about my own career path in terms of shapes and sizes of problems makes me realize that there are still a lot a lot of shapes that I haven't worked with. I think I'm a "Problem Solver" at this point, while also doing a bunch of "Solution Implementer" work but I'm far from being a good "Problem Finder".  

I have known about Chaos Monkey for a while now. If you didn't know, Chaos Monkey is a tool that Netflix developed and uses to test the resilience of it's network. Chaos and Monkey seems redundant because I don't think a Monkey's behavior in an engineering environment can be predicted but yeah, the idea is to make unpredictable changes to the software engineering environment of the application to see what happens. And more importantly, to ensure that the software is immune to such chaotic events. What I didn't know until now is the Simian Army . Latency Monkey Conformity Monkey Doctor Monkey Janitor Monkey 10-18 Monkey Chaos Gorilla Finally, "Chaos Monkey" is obviously obviously a genus with various subspecies   Simius Mortus Simius Quies Simius Amputa Simius Cogitarius Simius Plenus Simius Delirius Simius Desertus Simius Nonomenius Simius Noneccius Simius Amnesius Simius Nodynamus Simius Politicus Simius Tardus Simius Perditus Simius is Latin for ape, m...

The asterisk after first is because I have contributed to open source software that Enthought (my employer at the moment) maintains so these are my first contributions to a project which isn't maintained by Enthought. Also, i'm not counting opening issues on open source software as contributions at the moment, which I have done a couple of times in the past. In this specific case, I was looking at code in the Jupyter ecosystem in Python and I came across a few trivial changes that could be made in the projects, given that they dropped support for Python 2 and only supported Python 3. Remove u string prefixes from ipykernel, Remove Python 2 compatibility code from ipykernel, Remove Python 2 compatibility code from jupyter_client . There are actually a few more PRs (5 more, I think), for  which I am waiting for reviews. But they all make pretty much the same kind of changes. If you took a look at the PRs, you will notice that the changes themselves are extremely trivial and prett...

 I came across the bangbangcon conference a long long time back and I came across it again this weekend. It's nothing like the other software conferences that I have come across. Here are four amazing talks that I think exemplify what the bangbangcon is all about.  

 I purchased the O'Reilly Humble Book Bundle two weeks back and I've just read my second book from the bundle. So far, I'm pretty happy with the purchase. I paid for the full bundle and last weekend, I read Introducing Go and today, I read 97 Things every Java programmer should know  and i'm pretty happy with both. "Introducing Go" is a short book that introduces the Go language. The part of it that I found most interesting was the last chapters, one of which introduced Goroutines i.e. coroutines in Go. That leads nicely to looking at "Using Asyncio in Python". I browsed through  Think Julia  and  Using Asyncio in Python  as well last weekend, the latter of which made my head hurt. I'll prolly take a closer look at "Using Asyncio in Python" next weekend. "97 Things every Java programmer should know" seems to be part of the "97 Things XYZ should know" series of books by O'Reilly. There were a lot of "Things...

I was looking at a small dam the other day and I was marveling at the engineering. It was raining a lot and a couple of gates were lifted to release the water. Water was gushing through the open gates, sending out ripples on one side and foaming on the other. If not for the traffic, it sounded like a beach, water breaking on the sand. Feynman once said that understanding the science underlying nature only makes it more beautiful. It goes the same for man-made structures, in my opinion. My thoughts drifted to thinking about the civil and mechanical engineers who were part of the construction effort of this dam. Even though it's not the biggest, it's a significantly large structure in the area, something definitely to be proud of. Passersby might, every so often, appreciate the structure, it's resilience and it's grandiose. Civil and mechanical engineers have that advantage. If they choose to, their work is front and center in people's eyes. Civil engineers can ...

If you didn't already know, keyboard shortcuts can be used in GMail e.g. to compose a new mail, to archive a read mail. Those two actions (compose/archive) are the shortcuts I most use and I love it. But BUT! every so often I end up pressing a key, by mistake, that archives a mail which I didn't intend to or worse, deleting one. You might say that I can disable the action by clicking on `... undo` but if I perform multiple actions, I can't undo them all. And bringing things back from the Trash is easier for me because my Trash is almost always empty but bringing things back from the Archived section is harder because it's not ordered by most recently archived. I wish I could selectively enable/disable keyboard shortcuts. I dunno if GMail already can do this. I dunno if there's a way to add this functionality to GMail. I dunno if a different email provider has this functionality. Do you know?

This post/video is, IMO, a sister post of the previous one - https://rahulporuri.blogspot.in/2016/12/on-bias-at-work.html . The video, embedded below, talks about ethics in software design and the IT sector in general. All of us have seen these so called Dark Patterns on the internet/websites. Watch the video and you'll probably recognize a number of them. Better yet, visit the website : http://darkpatterns.org/ and you'll find more examples which couldn't be covered in the talk. Just watch the talk, I'm not going to give you a summary. What I want to talk about is the topic of Ethics in the Software Engineering world. Engineering Ethics is a course every student sits through in college. For most it is a formality. And given that now-a-days most college graduates end up working with and actively developing software, it is important to understand and lookout for ethical boundaries that we might be crossing while developing software. There is another beautiful/...

I just watched this brilliant keynote today. It's a commentary on Programmers and the software development industry/ecosystem as a whole. I am not going to give you a tl;dr version of the talk because it is a talk that I believe everyone should watch, that everyone should learn from. Instead, I am going to give my own parallel- ish views on programmers and programming. As pointed out in the talk, there are mythical creatures in the software development industry who are revered as gods. Guido Van Rossum, the creator of Python, was given the title Benevolent Dictator For Life (BDFL). People flock around the creators of popular languages or libraries. They are god-like to most programmers and are treated like gods. By which, I mean to say, we assume they don't have flaws. That they are infallible. That they are perfect. And alongside this belief in the infallibility of these Gods, we believe that they were born programmers. That programming is something that peopl...

Because I have nothing better to do on a Friday night, I downloaded whatever data that Facebook had on me, which you can as well by going to this part of Facebook  and clicking on the "Download a copy of your Facebook data". It might take a couple of minutes but you'll finally get a zipped file, one that will contain a "wall.htm" file inside of it. The contents of this "wall.htm" file is what I'll constrain myself to at this moment. Here's a small part of the file to give you an idea of the kind of information available in this file. 1 2 3 4 5 6 7 8 9 10 11 12 <p> <div class= "meta" > Monday, January 11, 2016 at 1:13am UTC+05:30 </div> Rahul Poruri shared Lunarbaboon &#039; s photo. </p> <p> <div class= "meta" > Sunday, January 10, 2016 at 6:32pm UTC+05:30 </div> Rahul Poruri shared a link. </p> As you can see above, there between th...

I am currently working on an assignment where the students in my class are expected to go through a book and make a list of all the errors we can find in the book. Well, to be fair, it's actually 10 chapters of a book and ~20 pages on an average per chapter. Well, the lazy engineering students that we are, we formed a group and divided work/chapters among ourselves so that none of us will have to read the whole thing but all of us get full credit. BTW, this is for a humanities course titled 'Environmental and Resource Economics' and the textbook we are expected to go through is called 'Energy and the Wealth of Nations'. And in this process, i came upon one interesting question. As i was reading the chapters, i noticed how hard it was for me to keep track of the errata. As it is a book, the whole thing is written in chapters and pages and if i do find a mistake, i'd have to note down the # of the page, the paragraph in the page and the sentence in that part...