💥 EXTREME documenting: My workflow

Writing documentation is one of those things we all despise.
It's boring, it's tedious and takes way too much time that we could be using to build a new feature, or to fix another bug.

However, we all know too how important is to have proper documentation (and if you don't, just wait until you have to work on an old, abandoned part of the code whose authors are long gone from the company).

(Dealing with legacy code is a whole other topic, but I always recommend this book if you are interested in learning more.)

In general, my advise is to write down EVERYTHING (hence the click-baity title) and filter it later if necessary. Act like if you were going to forget everything tomorrow (because you will).

Note taking

The good old reliable. What can I say?

I normally take notes by hand during my research but, after months and months, it's easy to lose them and, even if you find the appropriate ones, you will probably not understand them anymore, since you are not in the same mental space and they are likely to lack any structure.

My first iteration to solve this was to buy an iPad + iPencil. That way I have my notes synced and centralised, and I can rearrange / organise them.
But of course this is still less than ideal and it still means that if I leave the company that knowledge leaves with me.

Recently I added Notion to the mix, but I'll write another article about that.

Leverage your wiki

If a notebook is your personal knowledge hub, the wiki is your team's (or even the whole company's). It's your shared hive brain.
Every team should have one (and if you don't, I strongly suggest you to set one up asap).

It doesn't really matter if it's Confluence, Notion, or a Git repo with a lot of Markdown files (I've even read articles recommending adding a Markdown file for each source file, in the same directory), the important part is to have it easily accessible and modifiable by all team members.

Equally important is to keep it updated and reviewed!
I like apps like Notion, but a great advantage of simpler formats like Markdown is that you can easily integrate documenting into your usual code review pipeline.

Level up your ticket game

My next step into documenting fanaticism was a while after fixing a particularly complex bug. I had to go back to fix a new related issue and I found that I no longer remembered the inner workings of that system. The main issue was that I found the solution of that bug on an article online, and I didn't remember where.

So I decided to start writing down every source of information I used, not only my own thoughts/ideas.

But that turned out to be a lot of information, so I needed a better organising system.

My solution was to create a Notion template for a ticket/bug with all the fields that I'm likely to need in the future.

Hoarding browser tabs / links

We've all been there, tens of open tabs, with StackOverflow posts, blog articles, YouTube videos...

It can get hard to navigate, even overwhelming. And on top of that, what happens to all of that when you're done? Normally just closed and forgotten.

That's why nowadays I put them into their own list on Notion.
That way I can safely close the tabs once I read them and I know where to find them when I need them again, be it next hour or next month.
And it keeps my browser lean and tidy too.

Logs

Logs are your friends. No matter how much loggin are you doing, you should probably do more. Period.

I keep any related / suspicious logging message saved too, that way, if the bug comes back from the dead, I can check if the logs have changed.

Ticket postmortem

We already do this for whole features / products, time to go down to the ticket level.

All the information above can be a lot to process weeks/months down the line, so a quick summary of what you did to fix/implement it and why can save you a lot of headaches.

Diagrams

Maybe it's because I'm a very visual person but for me, there's nothing better than a flow/class diagram to get me to understand how a piece of code works/is structured.

Code can sometimes be a labyrinth and diagrams are your map. A map that can be improved and updated by and passed to other team members.

A lot of people like to use UML diagrams with things like PlantUML, that allows you to create diagrams through a text file that can be easily added to your version control system of choice.

But I personally prefer Diagrams.net (previously known as Draw.io) because you don't need to learn a whole new syntax and you can rearrange and color code it as you please. Its save file format is basically xml so it is git-friendly too.

Trick yourself into writing

Now to the hardes part, actually doing it.

We don't like to write documentation for a reason, and a super detailed and strict new system is not going to make it any easier (specially if imposed from upper management).

So the most important thing, more important than the system itself, is to build the habit of documenting our work.

For me, documenting is a pretty mindless chore, since I already take lots of notes during normal development. All I have left to do is recopilate and organise it. So I choose the most boring and lowest energy moment of my day to do it: the afternoon slump.

At that moment of the day my mental energy is non-existent and any attempt at actual thinking/reasoning will be fruitless, so copying notes into a database is easy enough to do and ramps me up into more mentally demanding work.