How We Use Notion To Document Code

The majority of developers don't document and categorize answers to complex problems.

We'll spend hours scouring the internet for answers, trying every possible solution, eventually finding one, and expect our brains to remember the answer the next time we experience the same problem. Fat chance.

And what about when you're working in a team? How do you know that another developer on your team hasn't experienced the same issue as you?

We need a way to track, categorize and index the solutions we find so that we help our future selves and our teams.

Let’s dive in.

Some background...

Within a year, our team at Origen Software grew from 2 to 8 which is amazing but definitely poses difficulties around scaling and knowledge sharing. We've tried a bunch of various approaches, solutions and tools to help ensure that our team is all on the same page and everyone has the information that they need to do awesome work.

No tool has brought us more success than Notion. We use it for nearly everything. From meeting-notes to planning company retreats (we're on one right now actually), we'll use Notion.

In my earlier days I was tracking my research using a private git repository and some Markdown files. I found it to be very useful for myself but not the best for indexing data and sharing with others. I needed to change things up.

That prompted wanting to implement an approach to helping the developers ensure we are all learning from one another's research and not potentially repeating the same mistakes.

It's worked wonders.​

Get Set Up

If you are unfamiliar with Notion, follow this link to get set up and create your account. If you're like me and enjoy using the desktop versions of applications, you can download the Windows or macOS version here.​

From there, you can go ahead and create an organization and start adding your team members.

You'll most likely get carried away with all the awesome features but let's focus on what we are here for: setting up a database to help your developers.

Create Your Template

First off, you'll need to create a new page. You do this simply by typing a "/" on any page. Create a new page and call it whatever you like. I'll use "Q&A" for explanation purposes.

Then, we need to create a new database. Use the "/" again to create a List view database.

Once you have created the database, you can spend some time naming it but then you'll want to hit the "New" button.

That should bring up a drawer for you to add a record. Before you get started adding a record, let's make a template to make things simpler and more guides for anyone wanting to quickly add something to the database. Hit the "create a template" button.

​​​

Then we just need to add some predefined properties to be filled in on each new record creation. Here's some basic ones that you could use:

​

• Owner - The creator of the record
• Project - Which project the question and answer were found
• Technologies - List the technologies that were used e.g. React, Redux
• Problem Explanation - Breakdown the problem and add error messages that occurred
• Useful Links - Add some links to videos, articles, StackOverflow questions that helped find the solution
• Pull Request - A link to the pull request that ultimately included the answer so other developers can gain a better understanding of the implementation
• Answer Explanation - Breakdown how you solved the problem and why that solution was the best one for your scenario

These are just a couple of my suggestions but you can really make this your own and add properties that are useful to your team. Add as many or as a little as you deem fit.

Use The Database

Now you just need to ensure your team is using the database.

Anytime someone asks you for help on a complex problem that takes time to solve, add it to the database. When you're stuck thinking about something overnight that you eventually solve the next day, add it to the database. It's worth it in the long run. For yourself and your team.