In my recent projects, I introduced one technique that helped me improve my productivity and reduced the time I spend doing things that I have done in the past but couldn’t remember anymore. I call this technique a personal worklog.
Why should you have your personal worklog?
Project setup
After switching projects a couple of times at work, I realized that there was always the same pain of setting everything up. Installing the development environment, configuring all the tools, and so on. Each time I felt like I was reinventing the wheel because I couldn’t remember what I had done last time. At some point, I started collecting chaotic notes of my steps. I pasted code snippets and commands that I ran in the terminal.
Solving issues with trial and error approach
From time to time I also have technical issues. I updated my machine and all of a sudden, the package manager command that should just install packages started to fail because it can’t build the dependencies. Trying to find a fix is usually a painful trial-and-error process. It involves trying out different commands found on Stackoverflow or GitHub threads. You check a solution, and it doesn’t work, you check another, and it doesn’t work either. After millions of iterations, it turns out that your first step actually caused the second – the correct solution – to break. Having a log of your actions and commands you can try to go back and forth and check what caused what. After I finally solve the issue, I have a history that I can go back to in case I have a similar issue again.
History of events
At some point, I had a chance to read Google’s SRE book (Beyer, et. al, 2016), especially the chapter about managing live incidents and I realized that what I did actually made a lot of sense. Maybe I wasn’t dealing with live incidents, but the idea of having a chronological order of events and actions could be very useful when trying to figure out what happened and why. It helps with writing postmortems too.
This made me introduce timestamps into my document, so not only did I know the order but also when things happened exactly. It could help correlate my changes with the potential issues in the system.
Recreating via UI
Then one interesting disaster happened. A company I was maintaining a website for forgot to pay for their server. It was a miscommunication on their side, as they thought the reminder emails were irrelevant but the outcome was we had to recreate the whole website – ironically and thoughtlessly we had backups but kept them on the server that had been removed. We had the code for the website, but it was based on a CMS, so most of the work was recreating content and configuration in the UI. So I decided to make screenshots and describe every step that I took – just in case something similar happened in the future.
How to write a personal worklog?
My initial way of writing my steps was to use a piece of paper but this quickly turned out to be useless. You can’t search in it, you can’t copy it and it’s hard to archive it. When I introduced the idea of using timestamps I moved to Slack and started writing messages to myself in the form of a Slack thread (one thread per problem). This was nice, it gave me timestamps for free – each message had the timestamp. But I wanted to have easy access to the log, maybe even share it, or export it. So I moved to Google Docs and this is my current way of keeping my personal worklog.
I insert dates and write under them. The longer I am within a project the less often I write to the log, but that’s ok. From time to time I still have issues or problems that I solve for the first time so I keep using it.
I also have a separate worklog for this blog 🙂
What should you include in a personal worklog?
The main idea is to put everything that is useful. These could be for example:
- code snippets
- commands to run in terminal
- description of what you did, step by step + information if the steps worked or not
- screenshots of the UI if the steps require clicking the right buttons
What you should NOT include in a personal worklog?
In case some commands or snippets include secrets try to remove them, and paste a reference where you can find them. It’s not a good idea to keep secrets as plain text in an unencrypted file. Additionally, it makes it harder to share the document in case you decide to do so.
Conclusion
Writing a personal worklog is a useful technique that helps you store knowledge that you get as you work through challenges in the project. It solves as a personal knowledge base which means that you don’t have to solve the same problem twice.
It could be a simple google docs document with timestamps that includes a description of the step taken, screenshots, code snippets, or terminal comments (without secrets). The idea is inspired by SRE and live incident state documents. Additionally, It helps to reproduce steps in case the work requires a lot of work using UI that could not be written in form of code.
References
- Beyer, B., Jones, C., Petoff, J., Murphy, N.R., (2016), Site Reliability Engineering: How Google Runs Production Systems, O’Reilly Media
