Navigation Menu

Skip to content
GitHub Universe is back: Get tickets now for 35% off, only until July 8

Your future self will thank you: Building your personal documentation

In Part Three of this series, Monica explains how to build a second brain of knowledge you’ll use over and over.

Monica Powell

Artwork: Susan Haejin Lee

Photo of Monica Powell
Newsela logo

Monica Powell // Senior Software Engineer, Newsela

The ReadME Project amplifies the voices of the open source community: the maintainers, developers, and teams whose contributions move the world forward every day.

Don’t Repeat Yourself (DRY) is a  common software mantra. In other words, you should write software in a way that isn’t overly duplicative of code that has the same functionality or value. Similarly, developers can take a DRY approach to how they search for answers to questions they encounter multiple times. By relying on an internal database (or “second brain”) they can reduce their reliance on external search engines. I've found when encountering a similar issue it is often more efficient to reference my own notes as I’ve already written them in a way that makes sense to me rather than to go through the process of parsing through search results until I encounter what I am looking for and then go through the process of translating how it’s written into a mental model that works for me. Being comfortable researching problems that are novel is a helpful exercise to go through as needed, either initially or for a refresher, but can become an inefficient bottleneck if I end up encountering the same problem multiple times but am not able to recall the details of what I previously learned and have no notes or breadcrumbs to help my future self get there without conducting an external search. 

Build a habit of note taking

You can begin a catalog of reference-able notes by documenting your learnings on a daily basis. Some developers maintain websites or GitHub repositories containing short snippets of something from that day’s learnings. Take for example this collection of 1,100+ notes written by Josh Branchaud. The “Today I Learned” (TIL) format of summarizing what you've learned in a few short sentences daily can be particularly helpful for folks who are committed to consistently taking notes in that particular format. However, since it’s more of a rigid, streak-based approach to note-taking, TIL can be demotivating for some individuals if they miss a day for one reason or another. I do think it’s important to take notes frequently in a way that you can commit to consistently, even if it’s not overly structured with a specific artifact for a specific interval of time. Maintaining a body of notes that you can review from time to time can be helpful for truly seeing the breadth of what you’ve learned over a given time period which may not be as obvious while you’re in the weeds of learning. 

While the TIL examples I’ve seen have been public, it's still valuable to regularly take similar notes summarizing your learnings even if they are intended to remain private. Writing with the intent of writing for your future self, as opposed to a larger audience, can reduce the cognitive load required to compile notes and make the note-taking process less time-consuming. In the future, if needed, private notes can always be refactored and revisited to be presented in a way that resonates with another audience. Often when brainstorming content to write or speak about I reflect on things that I found value in learning three months ago and often can draw inspiration from general themes in my notes. On the opposite end of the time spectrum, three months into the future you may benefit from a quick refresher on something you learned today. Therefore it’s helpful to loosely think about your future self and write notes in a way that will help you quickly get up to speed tomorrow, next month, or even several months from now if needed. Taking notes that aren’t intended for a larger audience should largely be approached with the intent of setting your future self up for success.  

Optimize notes for future searchability

There are numerous ways you can approach structuring personal notes. I’d recommend taking a lean approach to structure in the beginning since there’s always the option to refactor notes over time. But with loosely structured notes it’s important that your notes remain organized enough that you can revisit them in the future and quickly gain the context without it being too time-consuming to add new information. In order to optimize for quickly finding information and easily adding new information I would emphasize keeping notes in a system that is structured and indexed in a way that is easily searchable but does not require a lot of manual setup for every new note in order to meet those requirements. My current preferred note taking system allows me to quickly group collections of notes together via tags but also has full text search capabilities if I need a more narrow search term or forgot to tag a particular note. I like the flexibility of this system because I can quickly add new information without worrying too much about it getting “lost” in lieu of proper tags. 

Brief notes throughout the day can be particularly helpful when switching context, meetings, focusing on a high-priority issue, preparing for a pairing session, or logging off for the day. Less verbose technical notes are best during pairing sessions or when summarizing findings of software investigations to provide more comprehensive context to others in an efficient manner. 

More robust notes are more beneficial as reference material that are designed to be frequently referenced and easily scannable like a cheatsheet. These more robust forms of notes could easily translate into the foundation for more public-facing learning artifacts at some point.

Supplement notes with external documentation and automation 

Over time, as you consistently take notes and optimize for being able to quickly search and scan your notes, you will begin to develop a valuable sense of what is worth spending a few extra minutes to capture. For a very detailed step-by-step note, it’s more valuable to have a note that links to third-party documentation as opposed to spending the extra time to write out the more detailed step by step process unless the flow is less likely to change.  For example, git workflow is less likely to change than the exact steps to release a new feature in a repository that you occasionally contribute to. In the past I manually looked up obscure commands that I needed to use occasionally but not often enough to memorize the exact syntax of. 

I became more productive after switching from being reliant on a cheat sheet or using a help command to confirm these commands to using my command line’s brain. In short, I transitioned from Bash to ZSH for my shell and set up ZSH autosuggestions  which will populate suggestions as I type based on prompts I have used historically. Setting up autocomplete has saved me the time I would otherwise spend having to run a command to list out the available commands or referencing my notes when I cannot recall the exact syntax. Instead, I can just start typing the command from memory, even if my memory of it is fuzzy, and before I get too far into typing autocomplete will provide me with meaningful suggestions that usually save me from having to type another command or reference my notes. For more information, check out my article about how I quickly set up this flow with ZSH and autosuggestions

These are just a few ways to document your learnings and decisions. In the next article in this series, we will discuss the importance of ensuring that you are regularly documenting your wins with a level of detail and perspective that only you can provide.

Gif of the author, Monica, using ZSH autosuggestions to confirm the syntax of a command. Dark screen with mostly white text populating.

And if you want to learn more about this topic, check out my previous articles from this series focusing on document-driven growth: 

Hi, I’m Monica! I’m passionate about making open source more approachable, elevating people through technology, and cultivating communities. I enjoy working with ReactJSJamstack, JavaScript, APIs + Markup, and GraphQL. I built React Ladies as a safe space for women and non-binary ReactJS developers to create and collaborate together. I like contributing directly to the open source software I’m using and also enjoy creating supplemental educational materials on my website. I’m also a GitHub Star ⭐️.

About The
ReadME Project

Coding is usually seen as a solitary activity, but it’s actually the world’s largest community effort led by open source maintainers, contributors, and teams. These unsung heroes put in long hours to build software, fix issues, field questions, and manage communities.

The ReadME Project is part of GitHub’s ongoing effort to amplify the voices of the developer community. It’s an evolving space to engage with the community and explore the stories, challenges, technology, and culture that surround the world of open source.

Follow us:

Nominate a developer

Nominate inspiring developers and projects you think we should feature in The ReadME Project.

Support the community

Recognize developers working behind the scenes and help open source projects get the resources they need.

Thank you! for subscribing