7 Reasons Why you Should Start Documenting your Code | by Khuyen Tran | Dec, 2020
And how to Document your Code using Notion
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.
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:
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.
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.
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.
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 `.
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”:
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
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.
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.
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:
Read More …