Great Developers document their research step by step
Boost your performance with step by step documentation
Any developer that has at least 1 year of experience, knows that most of the time is spent solving problems and learning new things.
The knowledge that we have allows us to write code like movie hackers (unless you are dyslexic like me and make allot of mistakes), but in the moment we need to do something different or new we hit a huge block, no matter the experience a developer has. This is why the most requested skill is problem solving.
Problem solving skill can be learned and improved
First things we need to learn is how to approach problems.
Many developers start googling, open many tabs and let them open in order to have ready the information in case it needs to come back. (this is one reason i choose the 32Gb of ram MBP instead the cheaper 16Gb).
This means that developers easily open more than 40 tabs on a debug session.
Is a good approach, it helps everyone to solve the problem and come back in case something is not clear, but somehow it feels that is not complete.
So let’s think about, what could we do better?
Take notes and document the research
The answer is pretty easy, take note and document with comments and font style.
The documentation doesn’t need to be perfect, but it needs to have lots of information, so put down as much as you can.
You can add as much information as you think is needed or even more.
There should not be such thing as “too much information”.
In a plain text (or mark down as I like to use) save an explanation and the link.
Save all of this information on a ticket, or into a `readme.md` file and link this information in the `git commit`, so that later when you or someone else will try to understand the “why”, it can find the notes and documentation and understand autonomously.
Small recent story
In this days we had to update the “aws_apigatewayv2_deployment”, using terraform, to add an additional header to an existing created api. At the first sight I was like “this is 30 seconds job, just add the header and use the command `terraform apply`”.
But it turns out that terraform was not able to update the api, and the header was not added.
And a 30 seconds job turned into a 3 days research. Of course we tried also the `terraform destroy` followed by `terraform apply`, which worked, we destroyed the resource and recreated.
During the multi days research, I found many GitHub issues, Amazon tickets about this issue.
Documenting everything and saving all the links during the progress, allowed me to create a story like documentation.
On Friday I was able to present to my team 3 possible workaround and no solutions.
My teammates asked the questions in the same direction my research went, and for me was awesome since most of the time I was responding with “oh, this is a great question, and the answer is at this link…” and kept on explaining the web page content.
Some other colleagues that followed my progress trough the jira ticket (where I documented my progress) were able to understand and know most of the stuff whiteout having me to explain my findings.
And this was a happy ending story 😁.
📆 Multi day bug research
Happens more often than we like to admit.
An obscure old bug that only 2006 forums talks about and still with no solution.
Or and obscure NEW bug like the black screen video that the new iOS 15 introduced, that has a few solutions but other are still unable to fix.
Anyone know the phrase “yesterday was working”?
Yeah it happened to all of us, that the update of a library or OS broke our code, and made us loose days of research for a fix.
🏁 Start by writing the issue first
Yes, first start writing the issue.
You may think: “ohh, this is a minor issue, don’t actually need to write it down. And is not even that important/complicated”
YOU ARE WRONG!!! 🚫
In a few days, after you stop working on the issue, you will forget what was all about.
Write down the issue as it is someone else that needs to fix it, and it need to understand what is in your head.
✍️ Put down the findings
Put down findings like:
4. Possible solutions
Write them down, you will clean them later.
Put down also talks with you colleagues.
🧹 Clean the documentation
Once you have found the fix, clean the documentation.
At this point think if you could leave everything there, or remove the fixes that did not work, or other that you did not use.
Remember that your fix may not be final and later you may need to use the other solutions.
Another great way of handling this is by moving other possible solution into another README.md file, just to keep them close and easy to find.
Documenting step by step is like doing exercise every day.
You won’t notice the improvement right way, but will definitely be visible later on in your career.
Thank you for reading it.
And if you like it, please remember that you can clap 🙏 and that it really helps me allot.