choong pw

As a software engineer, you are well aware that creating great software is not just about writing code; it is also about ensuring that the code meets the needs of the business and the users. This is where playbooks, runbooks, ADRs, RFCs, and design docs come in. These documents help ensure that everyone involved in the project is on the same page and working towards the same goal.

Design Docs

A design doc is a document that outlines the design of a software system. It typically includes information about the architecture, data model, and user interface of the system. Design docs are important because they provide a blueprint for development and help ensure that everyone involved in a project is working towards the same goals.

There are tons of design doc structures to follow. Such as c4 model or the design docs at Google. On the other hand, you can also look from the security POV to build your docs with Threat Modelling. You’ll be surprised how much you can uncover with this approach. 

RFC

RFC stands for Request for Comments. It is a document that proposes a change or improvement to a software system. RFCs are important because they provide a way for stakeholders to discuss and evaluate proposed changes before they are implemented. This helps ensure that changes are thoroughly considered and that everyone involved in a project is aware of the potential impact of proposed changes.

If your team is deciding on behalf of other teams, or you need input from the expert, is always best to present an RFC so that they can present their input. Otherwise, it is better to document the decision in the form of ADR. 

A good RFC usually has a due date for people to provide feedback. So that the RFC proposal will be implemented while the motivation for the change is still high.

ADR

ADR stands for Architecture Decision Record. It is a document that records the decisions made regarding the design and architecture of a software system. ADRs are important because they provide a clear record of the reasoning behind design decisions, which can help with future maintenance and development efforts. ADRs also help ensure that everyone involved in a project is aware of design decisions and the rationale behind them.

When dealing with complex decisions, always question if there is a need that this decision to be recorded. It goes a long way to have the docs ready if the stakeholder asks for them. And most importantly, to preserve the context.

Playbooks

A playbook is a document that outlines a set of procedures or best practices that are to be followed during a particular process or situation.

Simply put, we recommend you to follow but is okay to deviate from the plan where it makes sense.

In software engineering, playbooks are often used for incident management. They provide a step-by-step guide for responding to an incident, including who to contact, what to do, and how to communicate with stakeholders. Playbooks are important because they help ensure that everyone involved in an incident response knows what is expected of them and can work together efficiently.

Runbooks

A runbook is similar to a playbook but is focused on the operations side of software engineering. It provides a set of procedures for deploying, maintaining, and troubleshooting software systems. 

Simply put, is a step-by-step guide for you to follow to get something done.

A common example would be, how to perform a cross-region recovery, etc. Runbooks are important because they help ensure that operations are consistent and that problems can be quickly identified and resolved.

Conclusion

In software engineering, all of those documents are important documents that help ensure that everyone involved in a project is working towards the same goals. Each of them also served its purpose in different phases of the software development lifecycle.

If you’re a tech lead, have the right balance of docs present. Too much of them might drown your team with reading/updating the docs, while too little will make it hard for new joiners to onboard the team quickly. I would strongly educate your team to differentiate the above so that they know where to write or search for the information when needed.

Lastly, on personal experience, these docs have saved me on countless occasions when dealing with stakeholders. It also serves as a point of evidence for many things that the organization needs.