13

RFCs - Measure Twice Cut Once in Software Engineering

RFCs - Measure Twice Cut Once in Software EngineeringPhoto by Ida Rizkha, https://www.pexels.com/photo/preschool-kids-drawing-in-day-care-7415985/

RFC stands for Request for Comments. In simple terms - goal of these documents is to get feedback on the systems/standards being proposed through them.


Would You Get Operated by a Surgeon Who Thinks on the Operation Table?

Following is an interesting analogy stated by one my former CTOs whom I deeply respect and have worked closely for in the past.

surgeons-plan-before-surgery Photo by Jonathan Borba: https://www.pexels.com/photo/doctors-performing-a-surgery-in-the-operating-room-13697925/

Often surgeons discuss the problem and report with fellow groups in detail before entering the operation theater. The same goes for construction engineers who build skyscrapers they don’t just start building something and then decide what to glue next.

The top military leaders like to know every bit of the terrain and all the details of the enemy’s position and prepare a detailed plan before even thinking of stepping into the war zone. They take their professions seriously the stakes and morals are high here.

One question to ask ourselves here is - Is our profession less critical than the above? The code we write or decisions we make could impact the reputation of the organisations, make them lose tons of money or even deeply impact the lives of people who use the service.

Impromptu Engineering;

There are 100s of thousands of software companies globally. Millions of people work for them out of which many are engineers. And engineers solve problems, most of the time. Sometimes we engineers also invent new problems in quest of solving them.

One of the bigger problems we have is - technical collaboration. Which likely will exist at least for a few years - until machines can replace us completely. As we develop more and more software the industry has invented fancy processes and given them fancy names like Agile, Waterfall, Freefall(Development in prod), etc.

The classic flow of software development in most of the software engineering companies nowadays:

  • Talk to the customer.
  • Come up with high-level requirements on documents(PRDs - Where the project managers feel good).
  • Convert them to actionable chunks of work and document the action items(Jira Tickets).
  • Estimate the capacity(Grooming/Planning - The boring long meetings).
  • Start executing the plan(Sprints/KanBan/Whatever).

Excellent. This sounds like a nice way to do stuff. Isn’t it? But, if you’ve worked on a complex enough system with considerable team size - you know that sometimes steps 3 to 5 don’t work well. And if you have seen steps 1 and 2 don’t work well it is time to change the job.

engineer-chasing-sprint-goal Photo by RUN 4 FFWPU: https://www.pexels.com/photo/boy-running-on-pathway-2539281/

Let’s look at it with an example - You’re a part of an amazing talented engineering team developing a dating application. Let’s call the application as Finder. The project folks talked to users of the application and came up with a requirement - The users need a way to upload their attractive pictures. So they can satisfy the impractical expectations of the person on the other side. Simple right?

The process goes the usual route. You or someone on the team create Jira tickets and add the details of what needs to be done. Also, mention the endpoints and UI screens and then you point the tickets together so everything looks straightforward. You set a neat and nice goal for the sprint to deliver a picture-uploading feature. Happy days. The sprint kicks off.

Here Comes the Problem:

The implementation goes on until 3 days before the sprint ends - the PRs are up for review. You get X number of comments on the PR your teammate has respectfully pointed out several flaws and a major flaw that’d be a risk for the scalability of the feature.

You don’t like to change things at the last minute because that’s not what you were planning for. But because the flaws are genuine the company cannot afford to accept these risks and also you’re a great engineer you decide to fix things - we’ll see in the sprint retro.

engineering-comes-with-problems Photo by Tim Gouw: https://www.pexels.com/photo/man-in-white-shirt-using-macbook-pro-52608/

Now you have a strict timeline to rework the whole PR because of flaws noticed in the system. Let's say you managed to stay up late in the day and fix the flaws. Little stretch right? BUT. No worries. We’ll plan better next time. You got the PR merged, the feature is ready in the sandbox environment and ready to verify/ship.

But wait just a day before the production release - someone from the security department reached out to your team pointing out a potential risk in the database you’re using for this feature. Hmm, This seems like a show-stopper, we can’t ship this feature to production due to the risk. And we don’t have enough time to rework the database now. You also have to roll back the feature from the sandbox environment.

What Went Wrong?

Think about it. Is it you who has not done a decent job at building and fixing the most scalable, the most secure feature possible? Maybe... You could have been more proactive and figured out the gaps that the initial PR had and saved some time by being more cautious. But what about the security issue? There was no chance you’d have known about it without the expertise of the security team.

Hmm. Seems like a process issue. But how can we fix it instead of blaming each other? What if there was a way to share what you’re going to implement with fellow engineers and the security folks before you built it? Sounds better right?

But let's say if you now start asking them to go through each of your Jira tickets and point out gaps it might have. This would take up a significant amount of their time. Also, that’s only if your Jira tickets point out the complete technical details in it. We can, but the reality is Jira Tickets do not always contain hardcore technical details - At the very least they’re a way to estimate story points while being relevant to the product folks. Also, we split them into smaller tasks so it becomes hard to get the full picture with just Jira.

Okay. If not Jira what do we need? Maybe a blueprint of what’s being engineered? Which can be shared with everyone concerned before we build anything. Here come the RFCs.

What are RFCs and Their Origin?

RFC stands for Request for Comments. In simple terms, it's an aggregated design document that is solely intended for technical specifications. The simple goal of these documents is to get feedback on the systems/standards being proposed through them. Hence, the name Request for Comments.

The first RFC was written and shared in 1969 as part of the seminal ARPANET project. This was the first wide-area packet-switched network. It was an informal attempt to get feedback on the technical design of the communication protocol between the hosts. Simply, asking for comments on the proposed Host Software - RFC-1 .

jon postel Jon Postel - Photo by Wikipedia

Interesting era of RFCs: There was an interesting role specifically for editing RFCs back in the early Internet times. who was known as the “God of the Internet” - worked as Principal Designer for the TCP/IP protocol. Jon served as an RFC editor for some of the most important RFCs such as SMTP. A RFC was published as a tribute to Jon after his death - the tribute RFC.

You can find many RFC examples on rfc-editor.org some of them were also published as the humour of the brilliant folks who designed many of the important components of the internet as we know it today - the fun RFC.

Traditional RFC Structure.

As you can see in some of the historical and modern RFCs some of them are defining standards, some are proposing new system designs and some of them are just informational. Based on the context and the problem the RFC structure can be tweaked and there’s no strict rule as such. If you look at a recent RFC - has sections in which the problem and solution are explained in detail.

  • Summary of the RFC
  • Title
  • Date
  • Author
  • Status
  • Copyrights
  • Abstract of what the challenge is.
  • Technical details of the solution being proposed with visual illustrations and subsections.
  • Security considerations.
  • References.
  • Conclusion/Appendix.

As you can see the information above is crucial and there’s no meaningless text that’s been thrown in. Unlike the PRDs where a lot of non-technical details can be usually seen.

RFCs Do Not Have to be Strict.

However, the RFC examples you can find on the internet have a pretty helpful structure to start with. You’re not limited by it. A different problem might need a different approach hence a different way of documenting/snapping it on the screen. As long as the collaboration problem solves even a technical poem works with childish drawing works.

Here’s an RFC that briefly depicts an example structure for the initial problem we talked about: RFC Template . It does not include the details of a fully-fledged solution but gives a good idea of how it can be laid out on a pane of glass.

RFCs Do Not solve everything - They're like us.

Our art is as good as us - so believing that just because you’re following a standard practice does not mean there are no surprises. At the very least the RFCs give a central place for technical brainstorming.