The art of documenting your coding experience

This weekend, I did two things:

• I went all over my old personal projects on my server and my GitHub account,
• I tried the new React.lazy and React.Suspense features.

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:

• you know what this “something” is (eg. a new coding language),
• you have a small idea of an application to test this new “something” (eg. a great podcasts list).

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.

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:

• Date the experiment: it helps me understand the context of my project. For instance, was it a new feature I was trying? Was I a total newbie in this area at that moment?
• Describe the purpose: it reminds me what the project was about. I add the name of the new feature or technology I am testing. Sometimes, I can add an official link to easily find the documentation about it.
• Describe the project: it defines how I applied what I was learning with a concrete project. What app am I building? What does it look like?
• List the results: it shares the knowledge of what I learned from the project. Here, I make a small list of what I discovered (bad or good), what I understood and, sometimes, my feelings about the coding experience. I can also add a screenshot of the experiment if I was too lazy to build and serve a production version of it (which is most of the time).
• Explain the experiment steps: it describes my coding process and the current state of the project. It can be completed or not at all. Actually, it doesn’t matter. What is important here is to know how I tried to build my project.
• Fill the usual README sections: usage, install, requirements, credits, resources.

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.

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.