I have a lot more to learn. The more I learn, the less I realize I know. As I was learning more, I was quickly overwhelmed by the number of things I had to keep track of. The solution was too obvious.
Today, I will talk about getting in the habit of taking notes and documenting which have created a meaningful impact in my career as a developer.
Before we begin, documentation is not necessarily coded comments, design docs, or meeting notes. What I am referring to is not something official shared across the team, but rather your own personal documentation or note-taking.
- Why take notes
- It’s more than just code
- Note-taking should be fast and simple
- What to write down
While doing some debugging work at my first job, there would be occasions where we run into some weird quirks in the legacy system.
Often times engineers would just take hours to resolve the issue and simply move on to another task. Whenever a similar issue occurs, developers try really hard to remember the exact steps to reproduce the bug and solve it again. Countless hours were wasted.
I was fortunate enough to have a mentor who introduced me to the wonders of note-taking at work. She would habitually write down the steps that she took to resolve any issue, best-known methodologies, best practices, basically everything.
Eventually, her entire OneNote was the result of her years of experience, making her an incredibly efficient engineer.
More Than Just Code
Oftentimes, I find myself needing help to get past hindrances that have little to do with coding. Or worse, I ended up in a similar situation before and still now asking for help for the second time simply because I have forgotten the process.
At the start of a new job or project, there is always much that is new and unfamiliar. For the most part, they are not all just about code, but rather everything else around it; steps to apply for access, Git workflow, deployment processes, hotkeys of a new tool, some useful Linux commands, and much more. Keeping track of all that stuff right on top of your head is almost impossible.
Have a notepad, take notes, and recap most conversations and meetings as they end. You will make a strong early impression and have more coasting room down the road should you need it.
Keep It Fast and Simple
I know people who write highly organized and detailed notes. Me? I am just a bullet point guy.
Look, you don’t need to write tidy and fancy personal notes. Experience has taught me making it pretty while trying to tackle an issue isn’t sustainable. You’ll entirely lose track of what you’re doing or end up being that annoying person who says “could you please slow it down while I jot it down?”.
Personally, I take notes into “scratchpads” and then synthesize them later. Note-taking should be fast. Legibility should be the least of your concern while you are actively listening.
Do not waste time documenting in style. Your personal notes are just meant for you to refer to at the end of the day, so do it fast and simple! Besides, you can always come back later on and do some touch-ups!
What to Jot Down
To give you some ideas, here are some of the things that I write down:
- Steps to set up a local development environment of a project
- Deployment process
- Git workflow
- Useful commands and code snippets
- Steps to handle production outages and bugs
- Things that I am learning
- Learnings and post mortem from an incident
- Thought process of how I come about solving a problem
- Project ideas and shower thoughts
The point is — just make it a point to start documenting whatever you do. Working on a project? Roughly describe what your code, system, or solution is supposed to do, why it was required, what problems you are trying to solve, etc. If you decide to take a shortcut or implement something in a “non-best practice” way, leave a comment and explain why.
Personal notes at work can even include 1-on-1 notes, ways to file a reimbursement claim, steps to apply for annual leave, etc. Does your company have its own abbreviations, jargon? Write them down and share them with your new colleagues!
The best part about this is whenever more than a person asks you the same question, you could easily tidy your notes up and share them with the rest of the team. As my notes grow, I eventually find myself becoming a much more resourceful developer, making myself more efficient at work.
What if it already exists
Yes, some of these maybe have already existed, perhaps in the company’s engineering wiki or onboarding guide, etc. In that case, I would just add any additional notes and a link to the original source. Having a personal note on top of existing official documentation does not make it a redundant effort, they are different. Don’t be discouraged because of it. Often times I find personal notes much quicker to look up for information.
I take notes on articles I have read, talks or presentations that I watch, or any courses I take.
Taking notes does not only make you look better in the short term, but you will also find yourself becoming the holder of “secret information” as time passes. Working at a startup, writing notes can be incredibly useful as they could turn into official documentation for the team someday.
So, document. Document everything. Write more documentation than code.
The commitment to taking notes has been one of the best decisions of my life — not just professionally. It's a tiny habit that pays huge dividends.
I hope that you find this article useful and that it encourages you to start taking notes. Happy note-taking!