What is your process to document what you learn while writing code?

Once a teacher told me:

You don't need to know everything in software engineering but you should definitely know where to look for.

I document all the things I learn while coding. It's kind of a mini post. First I did it in Trello but know I feel more comfortable doing this in Dropbox Paper.

I'd usually include details about the reason I was doing that feature or why I was looking for that information to provide context, and also add code snippets, images, links to repositories or issues, quotes of people who commented on an important tip. Everything that looks important.

Alt Text

For example, one day I was building a feature that required PDF generation and I did it in the local environment with wkhtmltopdf. Everything seemed to work fine in staging environment but the day I tried it on a different one it didn't work. It wasn't working at all in the cloud.

The issue was DevOps team uses Docker Alpine images and this meant I needed to take more care about the dependencies installed. The process to figure out how to solve this thing included terminal commands, GitHub issues, API calls to AWS S3, and more.

All of the findings are well-documented, with links, images, and more, in case anyone asks me or I get to be in a similar situation I'd know where to look for answers.

That's kind of my process.

Do you have one? If so, share it in the comments to learn new ways :)

Edidiong Asikpo's photo

Your process of documenting what you learn is quite similar to mine Francisco Quintero. Usually, I write about what I have learned on either a book or on a Google doc created for the particular technology or programming language. I love to use my own words when documenting because whenever I come back to look at it, I quickly remember the function of that particular method or technology.

On a Google Doc, I add images, code snippets, and a brief explanation about the code snippet and links to resources that provide more explanation on the subject.

In my book, I draw out a diagram that explains the function of the technology or method, add brief examples of how it works, and when it can be used. For example, when I learn about padding and margin in CSS, I drew a box and indicated effects of either adding margin or padding to a box.

I think it is very important to document what you learn because you would most likely need that information someday.

Francisco Quintero's photo

Software Engineer & Ruby on Rails Developer

Awesome, Edidiong :)

This summarizes why I do it and have never stopped:

I think it is very important to document what you learn because you would most likely need that information someday.

I never thought of Google Docs for this purpose because I think it's code snippets aren't good enough but it's good to know it works as well.

Thanks for sharing how you do it :)

Sharon Leah's photo

Software Developer

Am so glad this information has really helped me a lot. I rarely document but now I will begin to. Thank you!

Arpit Bhayani's photo

My knowledge-base is powered by

Nuclino is where I write short or detailed writeups about "Things I have learned" and Microsoft Todo is where my "Things I'd want to know better" goes.

While writing code or doing research, if I am finding some concept amusing but easy to understand I copy and paste few materials from the source into a Nuclino doc about the topic; and these snippets of information is usually sufficient for me to either convert it into a detailed writeup someday, so at least refer while solving something similar.

If I find something that I don't know, instead of diving deep into the newer concept, I add it to my todo list with few reference links, usually, the top k google search results. Thus whenever I want to pick something new to learn I just go through my todo list and pick a topic to dive and once I start understanding the topic in detail I start adding it in Nuclino.

In a way, Microsoft Todo and Nuclino act as my two columns in Kanban board.

 - if a concept is easier to understand
   - make an entry in Nuclino
   - keep adding snippets of information
   - if while diving deep I stumble upon something relatively new
        - make an entry in todo
        - add some reference links to it
   - some day convert those snippets into a detailed write-up

 - if I have the bandwidth to pick new things to learn
   - pick a topic from the todo list
   - use the reference links added as a note
   - start researching continue the first ritual

If the writeup is detailed enough and topic is interesting enough, it goes out to the community through my weekly newsletter and blog.

Francisco Quintero's photo

Software Engineer & Ruby on Rails Developer

Thanks for sharing your way, Arpit.

The other day I found Nuclino and looks really good. It's my second choice if Dropbox Paper stops working for me.

I found your process really interesting in the way that you make space for picking up a topic to dig deeper.

j's photo

My code is usually documented in the code the doc headers have examples and links to the according rfcs or papers. The second level of documentation is in the tests where I write down how to use also explaining the why as comments.

I usually build everthing including the docker/VM images or ansible/puppet for the provisioning. So in there are certain compile steps and sometimes I add my own mirrors just for the version freeze and certain binaries are statically compiled in there as well. With an explaination of why and what should be in there.

The rest ends in the README as 'how' to use it, command examples etc. My scripts or programms are always meant to run 'out of the box'.

Also I tried writing some manuals in a markdown guide. But in my experience most people don't read it. that's why I stopped and started to put the documentation in the code or scripts. so I can generate the documentation from the code.

A rather pragmatic approach after spending weeks writing documentation that maybe one dev is skimming. I rather prefer them as MD in the repo I am creating.

Also my hashnode blog has some stuff in there. But I tend to put the information at the point where people are working with it or link it from the code.

Francisco Quintero's photo

Software Engineer & Ruby on Rails Developer

Thanks for your answer, J :)

In the end, the process one should use is the one that best fits. The important thing is to know where to look for(besides Google)

j's photo

stuff ;)

Francisco Quintero well yes my teacher used to say it when I was twelve about knowledge in general not about technical engineering. I think it's an paraphrased einstein quote.

I personally think localization is important but we're talking about age old graph theory concepts in the end. So linking is the key concept to me.

Brandon Dusch's photo

Francisco Quintero My process for documenting what I learn while coding is I use Evernote! While I've used Evernote for over a decade, over the past year and a half, I've been treating it like my own encyclopedia. I use my notebooks to represent broad, overarching topics/ concepts (Ruby, Javascript, Web Development, UI/UX) while I use tags for topics and concepts that are less general and more specific (HTTP, APIs, Data Structures). I also use tags for topics that may span between notebooks (ex. The "Data Structure" tag pertains to the notebooks "Ruby" and "Python" because both notebook subjects involve the more specific "Data Structure" concept).

Sometimes, though, I find myself dealing with an avalanche of information. But I still want to document the information at some point in the near future. My fix for that was creating a special Evernote tag named "Inspect_Note". Every note created with that tag is meant to be revised, researched and revised before it's officially documented. Evernote has everything I need: ability to add images, embed code blocks and I can use Markdown shortcuts to make my notes look more like README.md files. :D

One other added benefit: Since I host a blog on Hashnode/ Devblog, Evernote has become an excellent place to go for blog post ideas and insights!

I've tried other note-taking apps like Dropbox and Notion but none of them stuck with me as fondly as Evernote has. It's all about finding a system that works for you and fine-tuning it as you go.

Francisco Quintero's photo

Software Engineer & Ruby on Rails Developer

Awesome. At some point in my career I intended to use Evernote this way but never really found the way. Yours looks very organized and helpful.

I do keep using Evernote but for other stuff not related to my profession :)

One other added benefit: Since I host a blog on Hashnode/ Devblog, Evernote has become an excellent place to go for blog post ideas and insights!

Yass! I also use everything I document as ideas or material for blog posts. I have a huge list and whenever I feel like I want to write something, I just pick something from the pool.

Tapas Adhikary's photo

Francisco Quintero Your way of doing sounds great to me 👍.

Btw, I think this is not easy to do and maintain(at least with me). Over the time, I have learned what not to document so that, I do not feel paranoid of not following it often.

Finally, I have settled down to followings:

  • Anything that is shareable publicly, must have an entry here. Wherever applicable, should have related examples in github.
  • Something that is not shareable publicly(may be very much organization specific or proprietary), I would have private EverNote pages created to maintain those for future references. In these cases too, I try to create code examples and push to Organization's GHE.
  • I also bookmark my contributions to StakeOverFlow so that, I do not have to search for what quick hack I found before 😆.

It is externally important to have documentation some ways. I feel, it is equally important to share those publicly wherever possible.

Thanks for asking this question and great to read other responses too! Cheers!

Francisco Quintero's photo

Software Engineer & Ruby on Rails Developer

Thanks for sharing how you do it, Tapas.

I have learned what not to document so that, I do not feel paranoid of not following it often.

This is also very important. Trying to document absolutely everything is a way to madness xD

Amit Chambial's photo

My way of documenting is a little different. I usually takes handwritten notes while writing code .

Then after that I refine my handwritten notes and write a blog on it so that even after months I want to look into how I did that thing I can always see my blog . Also you can share your knowledge with the world 🌏.

You can see my blogs here

Francisco Quintero's photo

Software Engineer & Ruby on Rails Developer

Thanks for sharing, Amit.

I barely do handwritten notes but that's a good way to better grasp ideas or topics.

Also you can share your knowledge with the world 🌏.

One of the reasons I blog. Share the knowledge. 👏🏽

Mauricio E.T.'s photo

I'm still just learning and have no formal experience in working with developer teams but will offer my own experience.

When I first started learning I also wasn't sure how to document my progress. In the beginning, I was just bookmarking everything in separate folders in Google Chrome. Eventually I thought I would try blogging but that didn't work out so I stopped.

Fast forward to last year, I discovered 100 days of code. The way they had you essentially journal each day was very clever, and it was all done on GitHub. Unfortunately I did not complete the 100 days but I still documented many days. I hope to restart the hundred days soon.

Fast forward to present time, I now have a devblog on hashnode and recently signed up for Notion. Both of these offer very intuitive ways to document, journal and share my progress. While everything on notion will most likely stay private unless I share templates, I'll be able to share my progress as well as establish a personal website dedicated to my developer journey on hashnode.

If you don't have a Devblog yet, I highly recommend it. I also recommend notion.

Francisco Quintero's photo

Software Engineer & Ruby on Rails Developer

Thanks for sharing Mauricio.

I've also seen other people using Notion for this purpose. I didn't like it and preferred Dropbox Paper but yeah, the idea is to have some sort of documentation for ourselves.

Keep doing it. You'll be grateful forever :)

Brandon Hopen's photo

Francisco Quintero Have you become use to the process so much that the switching costs are not high when you go between editor and application (Google, Dropbox Paper)?

CodeStream.com is an interesting tool, which allows to comment on code as you are writing in editor (similar paradigm to Google Docs) and its free! It's particularly useful, if you have a teammate, you can ask a question and @them to answer with a simple shortcut.