7 Reasons Why you Should Start Documenting your Code
By: Khuyen Tran
Tags: Code, Notion, Documentation, Programming, Data Science

7 Reasons Why you Should Start Documenting your Code

Photo by NeONBRAND on Unsplash

Motivation

Even if you are a data scientist who is knowledgeable in a variety of tools and good at coding, you might still find yourself struggling to:

Decide the next steps to take for your project

Remember what you have done

Understand the results of your experiments

Get help from your teammates because they don’t fully understand the code you have written

You can use some sophisticated apps to fix these problems, but the most effective and easiest method is to document your code.

How you can fix these problems with Notion?

What is Notion? Notion can be called an all-in-one workplace.

I like to use Notion to document everything that is related to my data science projects because Notion supports every kind of file including code, pdf, and web bookmark. Notion also makes it easy to organize your contents and make them look nice with minimal effort.

I remembered my manager kept reminding me to document my code using Notion, but I was reluctant to document my code at first because I imagined it must be time-consuming.

However, I realized that it would be even more time consuming if I forgot what I have done and needed to reinvent the wheel. Thus, I decided to start documenting my code on Notion. Surprisingly, I was able to solve all of the problems mentioned above!

In this article, I will share the benefits I gained from documenting and show you how you can start documenting your code in Notion.

Some benefits of documenting with Notion are:

Keeping track of the progress of the company

It is good to keep track of what models you have worked on, especially if you are not the only data scientist in your team. The worst thing you don’t want to happen is to accidentally work on the same thing that your teammates worked on.

By creating a general description of what each member is working on, your teammates and manager will not only get updated on what you have done but also might be able to give you some helpful suggestions.

How to do it

To insert a table like above, select Table-Inline option. Now, you have a fully fledged table like above

After inserting text to the table, you can expand the text to a page to describe the details of the method.

Keeping track of the team’s ideas

In the team meeting, your team members offer some amazing ideas to tackle a problem. However, after the call, you might not be sure about what specific steps you should take next. To prevent this from happening, quickly write down the ideas of your team members in the meeting

It can be just as simple as below. Several bullet points should do the trick.

You know what to do next

By writing a rough sketch of your general plan before jumping into the project, you will know what specific steps you should take next. This might sound time-consuming but this will actually save you time by taking the right steps.

After revising your plan and your team members’ ideas, you can put ideas into actionable items by writing a TO-DO list at the end of the outline.

By having small and specific goals, you know the exact steps you need to get the work done and keep yourself from feeling lost.

If you find it difficult to write down a specific task, it is time to have a short call with your team to recap the ideas of the last meeting.

How to do it

To create a to-do list in Notion, find a to-do list block.

Now you have a to-do block. Tick the one that you have finished.

Preventing yourself from forgetting

Humans are quick to forget; thus, you might forget the specific details of what you worked on or discovered one week ago. Even though you might add some comments above your code, it is easy to get lost when looking back at hundreds of lines of comments and code.

There might even be some ideas that you haven’t turned into code yet.

Thus, write down everything you have found out like below. The act of writing will also help you to memorize much better.

How to do it

To create the inline-block code like above, start the code with ` and end the code with another `.

Helping you understand your results

After analyzing your outputs, you gain some insights, but unless you write down your observations, you and your teammates will not be sure what your outputs really mean and whether these outputs are meaningful to your company’s goal.

By writing your observations, you will understand your results much better. You could also highlight specific sections and tag your team to these sections to make sure they are informed of your results.

How to do it

To embed a chart like above in Notion, copy and paste the report you created using Datapane, then select the option “Create embed”

To highlight, click the 6-dot symbol next to the text and choose “Color”:

Finding out the mistakes in your code

No matter how careful you are, it is unavoidable to make mistakes in your code. There are two ways writing can help you detect mistakes in your code.

Have your peers review your code

Four eyes or above are better than two eyes. Why not have your peers review your code or methods after you finish writing them?

Notion makes it easy for you to insert your code and insert comments in any section of your page.

By showing nice code snippets and their explanations, your teammates will find it easier to understand your code and are more willing to help.

If you prefer pointing them to the GitHub repo to check out the code, Notion also allows you to embed a Github repo like below

You detect your mistakes by writing a description of your approach

By writing down the specific steps that you have done, you can see whether your approach is valid or not and whether you can improve it. I often realized my mistakes just by writing down what I have done.

How to do it

To insert a code block, insert three `. Choose Python if you want to have a Python code block

To insert a Github repo or any other websites, choose Web bookmark in the block options

Refining your approach

There are multiple ways to approach a problem. Sometimes, you might not even figure out any solutions yet. Instead of thinking about everything in your head, write down the exact problems you are facing.

Once you understand what problems you are facing, you will find it is easier to find the solutions to your problem.

Now provide possible solutions to your questions. If you are not able to come up with a solution yet, break down your question into smaller questions until you find some solution.

How to do it

Just write down everything in your head without caring so much about the formatting.

Conclusion

Congratulations! You have learned how to document your code using Notion. Documenting is no less important than any other data science tasks. The time you invest in documenting will give you hours back.

After being sure about what you have done and what specific steps you should take next, you will feel motivated to get the work done and improve your productivity.

Give me six hours to chop down a tree and I will spend the first four sharpening the axe. — Abraham Lincoln

If you prefer to use any other tools to document your code instead of Notion, feel free to switch to another tool. Choose whatever method works for you but never stop documenting your code.

The Notion page for this article could be found here.

I like to write about basic data science concepts and play with different algorithms and data science tools. You could connect with me on LinkedIn and Twitter.

Star this repo if you want to check out the codes for all of the articles I have written. Follow me on Medium to stay informed with my latest data science articles like these: