Par Fanny Cheung

The art of documenting your coding experience

A notebook and a pen placed in front of a laptop
Crédits : Nick Morrison

This weekend, I did two things:

Why am I telling you this? Because these two events mixed together gave me the idea to find a proper way to document my process when I am testing something new for me: a technology, a coding language or a library feature.

What I call coding experience

When you want to try a new “something” the assumptions are that:

I decided to call the mix of these two points an experiment.

Reading my old personal projects READMEs made me realise that, except the “Usage” part, which describes mainly how to install and start the project locally, there was no context of the project, nor what I did in it, nor how I did it. Even worse, sometimes, there was nothing and I didn’t remember what I learned from it.

An exemple of code without context: Create json for d3 force layout
    `npm start`
What the hell am I talking about? ಠ_ಠ

So, I tried to observe myself coding this weekend when I was trying some new features of React 16.6.

Building a new way to document my process

After observing my process and digging into a lot of my old personal projects, I built a process that I tried to transcribe into my last project’s README file:

Why this is important for me

Good documentation takes into account two problematics: the freshness of the information and the context of it. With experiments, we are dealing with context and history.

Randall Munroe comic about the history of Unicode
Crédits : Randall Munroe

I definitively think that good READMEs are important. The Art of README article gave me food for thought this weekend. I initiated this new process when I was coding my small application with React 16.6.

Maybe I wrote some stupidities in my experiment documentation. But, the most important thing is that I can go back to it and check how and what I learned at a very precise moment.

I tried to update part of my GitHub repositories following this process. It was awful trying to remember what I wanted to do four years ago. But, it was fun to re-read old code and to realise all the things I learned over the years.

We all have experience to share as a developer. Sometimes, we are too shy to write an article or to give a talk about it. Or, we don’t feel legitimate enough to do it. Maybe, this documenting process can create another way to share your thoughts and experience. A more personal way.

After all, on personal projects, the one who will be the most happy with a good README is you.

Thanks to Sunny Ripert for the re-reading and Stephen Whitmore who inspired me for this article.