Documentation
To document - Definition
Let's make something clear, to document is not to add comments to your code. It means, explaining the next point regarding any important development you have done:
- Input -> what we expect
- Output -> what we should return
- Middle steps -> what we do with the input in order to produce an output
- Different scenarios -> The different paths we took when producing the output
- Technical approach decided and the reasons for it -> answer to a future developer which is reading your code or checking the solution, why you took that approach.
It seems a lot but it isn't, you don't to have to write the bible but you have to write the essential to ensure anyone that joins could understand the feature. You want more arguments? Good documentation saves you calls and reduce person dependencies.
Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.
Regarding documentation, I prefer to adapt it as next:
Always document as if the guy who will fix a bug in productions is YOU one year later. Try to make your life easier!
Let's take the next advice from He-man:
About me
I'm a Senior Platform Engineer. I build and evolve Internal Developer Platforms — golden paths, self-service tooling, and paved roads spanning AWS governance, CI/CD standardization, and developer enablement — so engineering teams ship faster, safer, and more autonomously, with less cognitive load. My core stack is AWS, Terraform, and GitHub Actions, and I'm an AWS Certified Solutions Architect. I care deeply about paved roads, productivity, and documenting implementations so knowledge scales with the team (yes, I'm an engineer who likes to document 🧑💻).
You can check my experience here.
Personal Blog - cangulo.github.io
GitHub - Carlos Angulo Mascarell - cangulo
LinkedIn - Carlos Angulo Mascarell