Context

Two weeks ago, I started my new working adventure as a Site Reliability Engineer (SRE). In those two weeks, it's been a flurry of activities and a lot of drinking from the proverbial firehose. One thing that's helped me keep my head above water and really process what I've been learning, has been taking notes.

Here are some things that have helped me in the way I take notes.

Take Notes

Before you start a new job, you have to begin / renew your membership with the cult of note-takers by drawing blood from your hand with a quill. Make sure to ask about it if it's not in your onboarding package.

This is a joke, of-course, however the point still stands that taking notes is an important habit, nay, a way-of-life even, that if you are able to commit - will absolutely pay off hella bank 💰.

Especially in the first couple of weeks when you can get lost in the sauce of all the stimuli coming at you - taking notes has has been a life-saver for me in all this if not for simply being a forcing function to pause and process. It's the most impactful, repeatable activity that's helped me ramp-up and build context.

There are so many advantages to this habit, but my biggest motivation for writing notes is that it's best early remedy for quelling Impostor Syndrome (which for me, spikes when I start something new). Taking notes provides an exercise that has a very low-barrier-to-entry where you can start excelling immediately. It allows me to say:

I might not be the best engineer in this room, but I will have the most / best detailed notes.

It's also a great way to be less of a burden on your peers and get quicker answers. Part of asking good questions is clearly defining what you know and what you don't know / need help on. Coming to a peer with a document that clearly defines the problem space, conveys what your context on that problem is and what you've already tried — means the more time that can be effectively spent on syncing state and working the problem.

👵🏽 If you come to me with a question that you've defined, what you've tried and what exactly you need - It is much easier for me to help you because you've already done the hard part. - An old mentor.

As with any habit though - the important part is commitment. You have to commit to taking notes - which if you're new to the practice, will take some time and repetition. The goal is to get to the point where opening up the notepad as your first-step, is second-nature.

Here are some things I do to make note-taking a part of my process and build that habit:

1. Use a system that's easy to maintain.

   My whole system only has two types of notes.

2. Hook notes to process.
   I create notes at the start of things (days, tasks, meetings) and reference notes at the end of things (PR's, summaries, agendas). Tying notes to process builds the habit.

I also have a standing tab on the very left of my browser that's meant purely for taking notes.

I'm fortunate that at this org, they've gone all-in on using Notion (which is what I've been using for personal notes as well) - which provides the benefits of being able to easily copy and sync notes from sources of truth, create powerful templates that fit my workflow as well as easily share notes for review with team members.

If you're not able to use Notion, I recommend using a markdown editor of some sort. One that I've had great success with in the past have been:

• Bear
• Typora

The reason I recommend markdown, is because markdown is the defacto standard for documentation in tech. This just allows interoperability if you end up wanting to copy/paste things from your docs to code or vice-versa.

But it doesn't have to be a flashy tool - even a word doc will even suffice.

The System

There's probably tonnes of literature and study on organizing information (in fact, there is - library science) that are probably much better thought out - however, here's what works for me.

I have 2 types of notes:

1. Daily Log
2. Detailed Notes

By default everything goes into the Daily Log is organized by date as recording your actions through-out the day. If something warrants more explanation (see below), it goes into a Detailed Note. The Detailed Notes should be linked to in the Daily Logs but can also be retrieved from a list.

They are split up in my note-taking tool (Notion) like this:

The first half are my Daily Logs and the second half is my Detailed Notes. The Detailed Notes section is broken down further into notes that are created dynamically ad-hoc, and those that are specifically tied into my own personal to-do list (which is just a different notion page, that has a kanban board).

1. Daily Logs

In Notion, I'll create a doc every-time I start a new day. This doc has my updates on things that happen through-out the day (kinda like a journal). This is especially helpful if I'm juggling multiple streams of work at once but mainly serves as a place to organize my flow through the day, and serve as a jumping off point for Detailed Notes.

Considerations

• Daily logs contain my stream of consciousness through-out the day.
  • Tasks I pick up (and why)
  • Things I hear and have questions about / want to investigate later.
  • Commands I see / things I want to research later
• If a single point on the daily log ends up taking more than 1 paragraph, consider breaking it off into a Detailed Note

Structure

Since I know that Daily Logs should be something I do every-day, I have them set-up in a template in Notion that I can easily create via 1 click every morning.

It contains only 2 headings:

• Important: (Anything that I should keep top of mind for the day - i.e. from my calendar/email)
• Notes: Where all my notes fall into.

Here's an example:

Important

• Meeting about X at 13:00 today

📅 Daily Log (Example)

• Standup:
  • Y is going to be working on cool-thing tomorrow, ask if I can ride shotgun
• Call with X coming up on Thursday to domain naming conventions
  • Read up on existing naming conventions for y

• Starting task #SYS-234 from backlog to patch ABC on <system> .

  → Detailed Note: SYS-234, patching ABC on system

• Paged for spike in slack mesages for #memechat

  • Investigated it: The data platform team was experimenting with a meme bot for hackathon.

• Continuing on SYS-234 → Link to detailed note

👾 Think of it like a systems-log, except you're the system.

If anything in the Daily Log meets the following criteria, I break it out into a Detailed note:

• The thing I'm writing about or working on can use some extra detail (i.e. diagrams, etc)
• What I'm writing about will stretch over multiple days
• What I'm writing about can be used by someone else
• It needs to be shared

💡A note on templates: Notion is great because it allows you to set and use templates. In my case, I have a template for Daily Log that I just create a new note based on every morning. However, in previous markdown note-taking apps, I simply created a markdown template that I would save as a text macro in something like atext.

2. Detailed Notes

These are more detailed notes that I can take in the process of completing a task or activity. They can also work for something like recording details from a meeting or pairing session as well.

Considerations

• They should be "self-contained" - these notes should be easily picked up by someone (lol probably yourself) in 6 months and have enough context to read-through to the conclusion.
• Notes should proceed from level of common understanding - > complex.
  • This means that base context should be built at the beginning of the note and then proceed to get into more details. Think of it as if you were teaching a class to someone else - you wouldn't start with the end-state.

What helps me in filling out these notes is when I think back to my early days working in Customer Support.

Whenever we got a ticket and couldn't solve it in the first interaction - we were trained to make Internal Notes.

The Internal Notes would contain things like Customer ID, and initial context (ELI5) so that if you had to go offline, another support agent could continue the ticket with enough information instead of having to establish base context again. The other time that Internal Notes would be used for - is when doing an escalation (i.e. escalating a ticket up to the next tier of support).

• A bad escalation is one where there's not enough information (especially from the customer) and requires to be sent back down to you. (An Involved effort required is required to proceed.)
• A sufficient escalation is one where the majority of information is there but still requires fetching some information. (Some effort is required to proceed)
• A good escalation is one where the escalation engineer wouldn't have to reach out to you to gather any more context to move forward.

Detailed Notes should be written in the form of escalation notes for yourself, where it should be able to take the reader from start to finish without needing additional context. This means erring on the side of over-communication and verbosity.

☝🏾 A Good Rule of Thumb for Detailed Notes: Ask yourself if a new-reader would be able to go from start to finish of a topic / lesson using your notes without having to ask question.

Structure

• Concise Title Explaining What The Note Is (Think about your choice of keywords / what it'll be like when you need to run a search for this in a couple of months)
• 1-liner purpose / explanation of what this note is (if the title gets too long i.e. for URL readability reasons)
• Link to completion details or TL:DR:
  • If this note aided you in completing a ticket, pop that in here. This will be helpful for later if you get similar tasks and need to create process OR if there's an outage and you're searching your personal notes for things that may have interacted with a thing of interest. (It's a needle in the haystack for your search later)
  • The TL:DR should be a 1-liner of the solution / thing you did or learned if possible.
• Context: <5W's, what should I know if I'm reading this as a new-joiner>.
  • Entrypoint <where did this task originate from (i.e. is there a ticket from the work queue like Jira or Zenhub?)
• Notes:
  • The meat of your note. This should contain anything/everything that you do and why you do it / why it's important.
  • Feel free to include checklists along with commands that you ran.
    • Pro-Tip: Include command output as well if you want to make it easy on yourself when you refer to notes during a high-stress situation (i.e. during an outage)
  • If there is another document / reference you had to read in order to do a certain thing, include it as a reference (and specifically, the portion from the reference that was important)
  • If you learn things from people through word-of-mouth or DM, include that in the note as quotes with timestamps
• References:
  • Other docs that are useful at a high-level (anything that is required reading for the content of the note should be referenced in-line)
• Conclusion:
  • Bring it all home with what was accomplished / what you learned.

The Benefits

• It's a forcing function to slow-down and structure information.
  • Humans speak faster than most people can type. Writing notes as someone speaks is challenging, but forces you to both process hearing the message, as well as writing it down.
  • Writing down notes also provides you something to look at in free-cycles which automatically incurs the sub-routine in your brain which tries to create structure and links. In these moments, you will find the gaps in understanding which you can act on to ask questions.
  • That delay also allows your internal-voice to ask: "Okay but why?" and if you can't recall the answer instantly - gives you a prompt to speak up and ask for the clarifying information.
• Leaving trail-markers / breadcrumbs along the way
  • Everyone climbs the knowledge mountain via different paths. However the signs that you leave behind can help out other hikers find their way to where they're doing. Similarly, every time you document some part of your infrastructure, you are doing the same thing for future engineers.
• DRY (Don't Repeat Yourself) Learning.
  • Don't Repeat Yourself is one of tenets of engineering that are de rigueur and yet, everyone seems to forget this when it comes to process and documentation. Every document you right, is less time spent trying to re-learn a system (especially when in incident response mode) and less time state transferring state to someone in the future.
• Build Training Materials As You Learn
  • Every note you create for yourself, is also an easily convertible candidate for documentation - to help others.
  • It's like a BOGO (Buy One Get One) deal for knowledge capture: wouldn't it be great if the next time someone joins your team, you could solve their entire question - or at least provide context for a large part of it because..you've gone through it before?
  • Creating a training program, much-less resources for that program is time-consuming. Documenting as you go allows you to hit two birds with one stone and when documents are able to be examined overhead - allows you to easily determine similarities and paths through the required knowledge — which in doing so gets you pretty far for building a training program.
• Auditability
  • You have a record of what you did if anything goes wrong (i.e. rolling back in case of an outage). You have notes to back yourself up if you're asked to explain why on something (which can help outline things you can change for a process)

Conclusion

Starting a new job can be a stressful position - requiring the absorption of large quantities of information. One excellent way to to help ingest, process and package information is in taking notes.

While it can be annoying to build up to the habit - some ways to incorporate it into your daily toolset is by (1) hooking it into process and by (2) using a system with a low administrative footprint. It can be hooked it into process by making notes a priority at the start and finish of different events (i.e. start/end of day, tasks & tickets). The process can be made easier to adopt by only having two types of notes: Daily Logs, and Detailed Notes.

A good rule of thumb for writing Detailed Notes is to ask if a new-reader would be able to go from start to finish without having to ask a question. This can be done by providing concise yet richly linked context, verbose instructions and an easily digestable conclusion.

Spending effort to take notes early pays off dividends - in the short term with helping structure and pace learning, and longer term by providing materials that can easily be re-purposed and shared for onboarding and training.