I like to maximize my growth by being more mindful and writing down some thoughts and takeaways. This is especially true when I have completed a project that involved a technology, pattern, or skill that was new to me. But my thoughts are rarely clear enough to just write down clear takeaways. In situations like this, I find it easiest to draw a mindmap to help interogate that experience.
I start with my experience in the center, and then ring it with interesting questions. Then I hang follow-up questions on those. Eventually I add answers. There can be multiple answers to a question. The output of this exercise can then be turned into atomic notes in my note-taking system.
Case study: writing YARD docs
A while back I did a project where I had to write a bunch of YARD docs for the first time. After completing the project, I wanted to mine that experience for some takeaways. I asked myself some questions like:
- what makes a high quality method doc?
- what am I hoping to see when reading method docs?
- how expensive are methods docs?
- when would I not bother writing method docs?
I try to ask the questions I encountered along the way when doing this project. I also try to put myself in the shoes of a newcomer to writing module docs and anticipate what kind of questions they might ask an expert.
Visuals
Mind maps are equivalent to tree structures so you can represent them in text form as nested bulleted lists. However, they are much more fun in visual form. My note-taking app (Obsidian), supports embedding Mermaid diagrams and mind maps are one of the diagram types offered by Mermaid but you could also use good old pen and paper.
Going deeper
Once I have the first ring, I start adding answers and follow-up questions. This doesn’t have to be linear, and answers can trigger new questions. It’s kind of like a dialog with yourself.
For example I have the question “what makes a high quality method doc?”. I might answer that with “it answers all of a reader’s questions”. That immediately makes me wonder though, “what kind of questions does a reader have?”. After some thought I respond with: “how do I use this?”, “what are the edge cases?”, and “why is this not behaving the way I expect?”.
Notes and beyond
I keep a note-taking system with short atomic notes where each title is a thesis statement. I was able to turn this set of questions and answers into the following notes:
- Avoid changing code while documenting
- Module docs are time-consuming to write
- Quality method docs are more than just type signatures
- Method doc type info needs more than input/output
- Module docs empower language servers
- Module docs are best on library code
This is often where I stop. In this case, I went one step further and used these notes as inspiration for a blog post on writing quality method docs.
