How thinking of Documentation as Legislation helped me become a better programmer

When I first started programming, it was predominantly creating applications that utilized the C++ graphics library. I was 14 and my friends and I tried to make the most of the time we got to spend at the computer lab of the boarding school we attended. We created applications that drew pretty, often animated pictures on the screen and not much else. This taught us basics, but our learning lacked any kind of structure. We read and figured out just enough to do what we wanted to do. There was no guidance.

When I went to college and ended up pursuing a degree in Electronics and Instrumentation, most of the programming I did was against a few micro-controller architectures and the odd C programming class. I learned a lot, but I did not delve in to the inner details of things. By the time I started working, I was a good programmer, but deep inside I always had the fear that I was faking it and that I was not good enough. When I had to solve things in new languages and technologies I often tried to find solutions that I could learn from and adapt as opposed to diving deep in to the details and inner workings of things. I was afraid that I wouldn’t be able to handle it.

At around the time I went to college, I had become really drawn to the legislative process and how legislation evolved. Interests in certain topics like the constant legal tussle that the Republic of India engaged with it’s States on the topic of the National Language ¹ compelled me to read the related legislation and court rulings. I slowly discovered that even though I was neither a student of Political Science nor a lawyer, I could understand legislation and court orders well enough because they were so specific—specific to the point of being boring.

This prompted me to look at documentation in another light. From being unnecessarily complex in my view, they became specific and often the place to see answers for contentious topics that brought conflicting interpretations from different people. Around this time, I had started reading the R.F.C.s ² of the I.E.T.F. ³ and it convinced me that well written documentation has the same qualities as well written legislation—specificity, context and lending themselves to being represented as change-sets.

This has had tremendously positive effect on my programming—instead of being afraid of diving deep and understanding for myself how a particular programming language feature or library or protocol specification, I see it something that I can understand really well if I spend enough time.

I have since come across projects that look at this similarity from the other side. There are multiple projects that tries to represent and record constitutions and legislation as version controlled repositories. The GitLaw idea has taken off with multiple version-controlled repositories of legislation—examples include Australia, New Zealand and Germany.