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

View other answers to this thread

Learn Something New Everyday,
Connect With The Best Developers!

Sign Up Now!

& 500k+ others use Hashnode actively.

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.

Want to read more?

Browse featured discussions

© 2020 · Hashnode