Continuous Documentation for Forgetful Programmers
And non-programmers too!
I’ve always considered my work-related memory to be subpar.
I would often be asked whether I remember how we implemented X or why we chose option Y; and even though we did implement X and chose option Y three or four times, the answer would forever remain hiding on the tip of my tongue and never show up. This here is a terrible feeling that would make me feel really incompetent.
One might retort: “Well, why didn’t you write down those oh-so-important things somewhere?”
I did. But I eventually forgot where. And the answers would change their hiding place from the tip of my tongue to some drawer swamped with papers and post-its or a text file amongst dozens of text files in my hard disk.
And one day, my mentor told me about continuous documentation.
Step one: write things down
Just start by focusing on just writing things down.
When something remarkable happens, write it down.
When something makes you happy, or upset; write it down.
Any disturbance in your general sense of flow at work: write it down.
As someone who tries to be organized, this is the moment when I would start overthinking how to write things down: “I need to find the right tool”. “I need to define a clear convention”. “I need to come up with a set of categories and labels”. “But do I need labels, or is it just enough with categories?”
Stop right there. It doesn’t matter. It can be just a simple text file for now. Let’s park the “making it look professional” for later. For now, just open whatever writing tool you feel comfortable with, and start writing those entries down.
Don’t worry about anything else now; that’s something for later! Don‘t worry if some entries are short and others are half a page long!
* We shouldn't be deploying to production on a Friday afternoon.☝️ Yeah, that’s a nice one!
- *MAYBE IMPORTANT* [my-nodejs-backend-api] [unit-tests] I keep seeing random disconnection errors from the knex library on the OpenShift test environment. It doesn't seem to cause any issues, but it's been happening for weeks already and probably some developer should have a look at it. It never seems to happen when running the service locally with docker-compose. Is there a way to consistently reproduce this issue?☝️ Also good!
* I think Toby is the Scranton strangler.☝️ Everybody knew it!
Focus on writing. The most important part comes in the next two steps.
Step two: meditate on your notes
At the end of the day, we will spend 5 minutes reviewing our daily notes. Make sure you mark yourself as “busy” on your work calendar and Slack, we do not want to be disturbed.
There might be some realizations here and there. Maybe an entry you wrote in the morning reached closure somewhere in the afternoon, and you have to amend it. You might feel like adding a final entry on today’s log with a general evaluation of how the day went. Maybe you will notice an entry that did not feel so important at the moment of writing, but changed the course of the day for good (or bad.) It could also be time to tidy up a bit the structure of your notes, if you feel up to it.
That’s good for now; time to go home!
Step three: find patterns
Every one or two weeks we are going to have a more thorough review of our notes. Make sure you put on your detective hat, because we are going to be looking for patterns.
Do you remember those times that something really annoying happens in the middle of a very stressful period, and you have to park it because there are more urgent matters to attend to? It’s easy to forget those annoying things once you feel the relief of having solved those urgent matters. This complication will probably happen again, probably during another stressful period. It will be likely forgotten again. This cycle might repeat dozens of times before one realizes it’s time to tackle that little annoyance.
That is an one example of the type of patterns we will be looking for. Pay close attention and try to find out recurring themes in your notes. It will be helpful if by the end of this session you have written down a nice summary of your findings. This will be a very valuable outcome of the continuous documentation process; treasure it and decide how to address them.
Time to get more organized?
I started writing my notes in a markdown file. One markdown file per month of the year (e.g. 2016–04.md). Like I mentioned before, in the beginning it was hard to resist the temptation of coming up with a proper standard of writing notes, or finding some fancy tool to organize them. Several years down the line, I’m still writing my markdown files and haven’t had the need to come up with anything fancier than that.
Some colleagues of mine use Bear, others who prefer digital handwriting use GoodNotes.
How did this work for me?
I started this article sharing my concerns about my poor memory. How did continuous documentation help me improve it?
In retrospective:
- Writing my notes and mindfully reviewing them daily and again every two weeks helped my memories “sink down better” in my brain. Substantially.
- In case I forgot something in particular, even the simplest editing tool has search functionalities!
Continuous documentation tl;dr
- Write things down.
- Meditate on your notes for 5 minutes at the end of the day.
- Review your notes every one or two weeks and try to find patterns.
