Every high performing engineer is fairly well-organised. There is no time to waste, when delivery is what you’re gunning for. Today, we’ll discuss three types of documents highly effective engineers always have at their disposal and how these documents help drive the product and your career forward. Let’s get cracking!

Improvement playground

Always within a few-clicks reach, improvement document is your playground. This is where you brainstorm ideas about possible avenues for improving the system.

Improvements can vary in their difficulty, priority, business value and so on. They can also vary with regard to what is being improved. Sometimes it will be underlying database configuration, others it will be a proposal for a UI change.

The details are not as important at this phase. What is important is that the ideas are written down, waiting for a better opportunity. If you’re looking to read about gauging the business value of refactoring efforts, look no further.

If you’re a long-time reader (3 weeks lol), you’ll remember a post about the importance of protecting your time ruthlessly, specifically a segment about zeroing in on the most important thing. The premise was, remove obstacles as quick as you can and focus on the P0 thing you started with. Sounds good.

However, we’re surely going to stumble upon the tangential problems on our path to delivery. Some of these problems and ideas that cross our mind during this time are the perfect candidate for this doc! Don’t go depth-first and solve the issue, just write the idea down and move on. Yes, gaslight yourself it’s not a big deal right now.

Here’s a few tips that have worked for me:

• ✅ create a segment per improvement (sub-page, nested documents, etc)

• ✅ review the document regularly (potential is only valuable once you take action)

• ✅ pick up items when you have some slack and convert them into full-blown proposals (or reject them and document the reasoning!)

Here’s some of the stuff that hasn’t quite worked:

• ❌ don’t impose structure on the segments (different problems, different structures, who cares)

• ❌ don’t do a deep-dive when you get the idea or encounter the issue

• ❌ don’t forget to include artefacts for easier reference (various screenshots, Sentry logs, capture the core of the issue/improvement while it’s in front of you)

Deployment log

The next document is the one we use for tracking deployments - on a personal level. This type of a document is a lot simpler and more straightforward. However, I believe it is incredibly valuable and it lends itself well to various customisations to fit your needs.

At a certain point during my career I had gotten so comfortable with deploying to production that I actually started making some reckless oversights due to this confidence. This is when I came up with a system to prevent this from happening ever again. I later found a lot greater value in my new practice.

The idea of the deployment log goes something like this: each time you’re about to deploy something to prod, you make a series of notes about it and then proceed. As the deployment is progressing, you keep track of it in the notes. When the deployment is live, you wrap up the notes. Check it out, then let’s break it down.

Deployment #123
--
Segment: Valuable service land
Change:  Delivered a thing, created profits
Reason:  Thing needed a thing for thing, for profits ofc

JIRA:    OC-3313
Github:  https://github.com/acme-corp/valuable-service/pull/144
Project: #offical-project-channel
-- 
Artefacts: screenshots, links, logs, written notes, document everything!
-- 
Artefacts: announcements, follow-ups

Notes have three segments. The first segment of each note is pre-deployment segment. This is where you write down what is it that you’re changing, where and why (briefly, but with clarity). Additionally, it helps if you include metadata such as JIRA board links, Github pull requests, Slack announcements, etc.

The second segment is not as structured, but critical. This is the mid-deployment segment and it has the purpose of recording the deployment as it is happening in real time. What you’ll be monitoring will depend largely on the type of change you’re making. But the idea is - have undeniable evidence that the system is behaving the way you expect it to. This means including artefacts such as screenshots, links, logs, your own comments, etc.

The final segment is some housekeeping. But we don’t neglect it anyways! This is the post-deployment segment and it has the purpose of recording that you’ve followed up with everyone who cared for it. Typical use-cases include announcements to the downstream teams (hopefully you’ve had one before the deployment as well) or sending out issue-resolution guide to the on-callers. Make sure you leave no loose ends.

Brag doc

You’re a top performer, congrats! All that hard work, all the effort and the hours… Now what? Now you want some buck for your bang! (bear with me) This is where our final document kicks in - the brag document. Also known as - The Kanye Doc.

I can not stress this enough - write down your contributions AS THEY HAPPEN. If you don’t, you’re up for a sweet treat once you decide to shoot for a promotion. That thing you’ve improved three months ago? Oh yeah, metric retention expired - no luck in obtaining evidence easily. That is given that you even remember what you were working on. I’ve been there. Boy, I have. It fucking sucks.

Again, what you collect precisely is beyond my jurisdiction - figure out how to tell the story. But figure it out while it is occurring. Everything is still in the working memory (your very own RAM) and readily available, use this advantage or suffer later.

All sorts of contributions should go here, ranging from large multi-month projects to occasional knowledge-sharing sessions you do once you feel inspired. Here are some of the sections on mine:

• projects I lead (driving results)

• projects I contribute to (supporting results)

• cross-team collaborations (wider impact)

• system & process improvements (scripts, automations, minor tweaks and improvements)

• mentorship & knowledge sharing

But literally anything can be included in this document, and it largely depends on the types of contributions you’re making and the promotion expectations at your company.

---

Thanks for reading folks!

I do encourage you to attack me in the comments.