How did you use previous knowledge to solve a software related issue?


Author: Jason Clarke


Published: August 12 2022

Aside from software engineering, I've studied law and was educated by world-class lecturers including Lij Sinclair who perfected the art of teaching Jamaican and Commonwealth legislation. A new challenge that arose in the workplace was the case of writing proper documentation and formatting pull requests. Documentation in this case refers to explaining in detail how the code is written and supposed to work. A pull request in simple terms is asking someone to review your code so that it is up to standard and can be added to the main codebase.

The issue was more than just documentation or pull requests, it was that there was no outlined structure on how to approach either. This inconsistency led to confusing material and poor quality of information. In an attempt to address this issue I decided to use the principles gained from my experiences studying law to provide order in software documentation.

When answering a legal question, the IRAC method is widely used. IRAC is a legal acronym that stands for Issue, Rule, Application and Conclusion. In other words:

  1. What is the issue that is being faced?
  2. What are the rules that apply to this issue?
  3. Have there been any successful applications of these rules? and
  4. What was the conclusion?

These questions also gave a great outline for writing technical documentation that is straight to the point and concise. After writing documentation using this method, it was adopted by the company and is currently the golden standard when documenting components, features or major updates.

Moreover, a simplified version is used for pull requests. We have discovered that including the Rule and Application for pull requests radically increases the time taken to roll out new features or important fixes. As a result, we have removed them and only require the Issue and Conclusion/Solution. This is quite successful and has improved the quality of pull requests.

Creating pull requests like this is so insightful that I even use this approach when contributing to open-sourced projects. For example my contribution to the Vue Style Guide which is used by thousands of developers worldwide.

In the image attached you will see a contribution I made on March 10, 2022 concerning a documentation issue they had. The pull request was later approved and my updates were added to the project.

Using the IRAC method was one instance of how I was able to apply my past knowledge to a new challenge in my career.