Skip to content
Cassidy Williams

Artwork: Kasia Bojanowska

Documenting knowledge: a guide to successful note-taking

How building a team culture around thoughtful note-taking can improve collective understanding.

Photo of Cassidy Williams
Contenda logo

Cassidy Williams // CTO, Contenda

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

What if someone on your team suddenly won the lottery? What if they signed out of the team chat, and you never heard from them again? Well, first of all, good for them, but would your team be in trouble? Would all of their knowledge go out the door as they sailed off into the sunset?

As your teams grow, so does the collective knowledge you've built together. It can be challenging to manage that knowledge, document it all, create new ideas without reinventing the wheel, and bring new team members into your space to add even more knowledge to the pile. Despite this difficulty, it is essential that turnover doesn’t lead to a significant regression in team comprehension.

In this Guide, you will learn:

  1. Why documenting knowledge is a meaningful process

  2. Best practices for quality note-taking

  3. How to standardize information gathering

What about that lottery winner?

If it isn’t the lottery, maybe it’s something less exciting that pulls your teammates away. If and when someone decides to switch jobs, work on something new, or even go on a well-deserved vacation, would your projects be in jeopardy? Would your team be able to manage?

The risk of not writing things down in a searchable way means that a person’s knowledge could be lost. Establishing a culture of documentation in which your team has a shared system of how and where they should write can help this. Now, you don't want to become data hoarders (regularly auditing notes and documents as being out-of-date or archivable is a good thing), but having the context available to anyone who might need it will pay dividends over time.

Also, it’s important to understand that note-taking is a team responsibility. Too often, this responsibility repeatedly gets put on the shoulders of the same one or two people, and once again: Everything about team notes should be shared. If a regular note-taker doesn't take notes or isn't able to, who will cover for them? I suggest developing some kind of rotation system to ensure that everyone is responsible for maintaining team knowledge.

A case for remembering

Writing down interesting ideas, meeting minutes, or even notes about conversations with teammates can be helpful to remember what happened throughout your day. Committing pen to paper is a meaningful process that helps to solidify concepts in our minds. Research has shown that “writing by hand on physical paper” stimulates significant brain activity, which could be associated with increased information retention.

When you want to remember something, you have to write it down. When you want to understand something, you have to translate ideas into your own words. Ideas and creative concepts snowball: The more you write things down, the more you start to develop a good knack for thinking up and tracking your ideas. Now, imagine if writing things down became a habit for your team. Think of what you could create together!

Sifting through to find what’s important

On the other side of the note-taking coin is the challenge of searching through your team's notes and documentation. Without structure, knowledge-sharing is rarely helpful. We lose context quickly as humans, and it can be hard to follow your original train of thought or understand the exact words or phrases you were using.

That being said, thinking too much about making your team's notes "searchable" can bog you down when writing them and is not productive. Ideas are fleeting and can be very powerful over time if captured well. Dedicating too much of your focus to content organization versus getting ideas down on paper can mean losing what you want to capture. To solve this, you need to have a predictable system for your notes.

There's a helpful principle from the book How To Take Smart Notes by Sönke Ahrens: Standardization enables creativity.

You don't want to spend unnecessary energy trying to organize your notes as you're brainstorming with your team and making decisions. You want to have an easy-to-navigate, predictable system for note-taking. When you have common formatting, organization, and a shared understanding of how to document things, your team can think, reflect, hypothesize, discuss, test, and collaborate more easily. This is the creative work that matters!

There’s no "silver bullet" system for notes. The way your team decides to take notes is up to your team. The key is to have a shared buy-in, in which everyone uses the same approach. You can try to build templates that people can easily pull from or have "scratch pad" areas where you can jot down quick ideas that you’ll organize later. You don't need to treat notes as if they're permanent, precious pieces of information. Notes can be composed together, moved, changed, and evolved over time, just like the code you write!

The PARA method

The Forte Labs organization describes the PARA method: a universal system for organizing digital information. The system’s four principles are outlined below:

  • Projects: a series of tasks linked to a goal, with a deadline

    • Ex: app mockups, product specifications, blog posts

  • Areas: a sphere of activity with a standard to be maintained over time

    • Ex: professional development, direct reports, products, writing

  • Resources: a topic or theme of ongoing interest

    • Ex: project management, linting, teammate information

  • Archives: inactive items from the other three categories

    • Ex: Projects that are completed or inactive, areas you’re not committed to anymore, resources that are no longer relevant

Following a set of guidelines like this can be helpful for your team as you establish your own best practices. Enabling your team's strengths in organizing and understanding information is particularly helpful as you establish a knowledge base for yourselves.

Moving forward

It's easy to either under-document everything because there's simply too much to know (and things change too often), or over-document everything (and then every single page turns into a deep rabbit hole of connecting information). Finding that balance is important. A culture of healthy documentation may take time to develop, but as the phrase goes: The best time to start was yesterday, and the next best time to start is now!

Want to learn more? Check out Cassidy's talk on Team knowledge-sharing at GitHub Universe.

Hi, I'm Cassidy! I'm based in Chicago, and I love coding, jokes, and mechanical keyboards. ⌨️  My favorite thing to do is help others to be the best that they can be, and I pursue that through teaching, building demos and starter projects on my GitHub, speaking, my newsletter, my live streams, mentoring, advising startups, and even just by making memes. 🤪 You can check out most of these things here. Building for the web has been a blast for me since I was a teenager, and I have no plans of stopping anytime soon!

More stories

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.