Whatever your point of view, I want to show you that maybe it’s not the documentation itself but the way you use it. I will share with you a recent example I experienced. Then I will share with you a new approach I discovered that has really helped me make much bigger progress in my work.
A Real World Example With ReactFlow
I’ve been working in an application at work which use ReactFlow. If you don’t know what ReactFlow is — it’s a react component that can be used to build node based UIs/editors which can also be interactive. See their examples page to discover some really nice real world use cases.
It’s a really polished library. It’s established, stable and comes with a bunch of neat options.
Before I started work on this project I had used the library a little and was somewhat familiar with the api. I thought that was enough. I was wrong.
When do I usually read documentation?
- When I am using a specific part of a library and I want to find out more about it — what props exist for example.
- When I am stuck — I’m not sure how to do something and hope the documentation will provide some clues
- When I am setting up the library for the first time — I need to find out if how to do some special imports or wrap my app in a provider.
- When I want to see some examples — I find it incredibly useful to see real world code implementations and then translate that into my own codebase.
I realised all these scenarios happen when I am working in the code. It happens in the day to day when I am stuck in the weeds.
Looking At Documentation Differently
What’s the problem I had then? It’s to do with what your brain notices depending on your current situation. Your brain is amazing at blocking out “noise” if it has a goal in mind.
I realised that whenever I visited any documentation I always had a goal in mind. I needed to find out what props a component could have or how to fix a specific issue. I was always looking for a something specific and then leaving straight after. I was like a horse with blinders on.
Press enter or click to view image in full size
One night when reading in bed, I decided to read the Reactflow documentation (as one does). I wasn’t using the documentation to solve a specific problem. I was exploring the documentation through pure curiosity. My brain was in “explorer” mode rather that “goal seeking” mode. It’s the whole right side of brain vs left side of brain.
I was discovering features and examples I had never seen before. I was learning my way around the documentation. Reactflow documentation is rich with examples and information, it’s not something you can consume in 5 minutes.
I found three features that I realised could potentially work great on the app I was currently working on. I was getting excited again. My brain started to run through possibilities and how they could be implemented.
The three features were:
- Node Toolbar — This opens up a whole world of possibilities when a user selects a given node.
- Layout with Elkjs — Some of the drawings in the app I was working on were getting incredibly messy. This helps organise the nodes and edges into a coherent layout.
- Lasso selection — Being able to easily select many nodes at once would be a real game changer.
This is something that isn’t spoken about much at the moment, especially with all the AI talk going on.
Here I was laying in my bed and I was making more progress than I would by spending 20 hours sitting at my keyboard.
Why?
I was taking a step back from the implementation and seeing the app with fresh new eyes. I was seeing the gaps and possibilities and then using the new found features I was discovering in the docs to fill in those gaps.
Then when it came to implementation it was easy. The hard work had been done upfront in my mind. Getting the code down in files was the easy part.
It Works Only On Some Documentation
One caveat I would be remiss to not include. This doesn’t work in all scenarios. Some documentation is just plain crap. There just aren’t good examples. This is one big reason I think why generative AI has been so successful — it bridges the gap where bad documentation fails.
This approach mainly works with great documentation. The likes of Reactflow or Tanstack query to name but a few.
Conclusion
I’ve always heard that well written documentation is so helpful when working with a library. This has brought even more meaning to me as I have discovered this different approach in reading them.
Software isn’t just about fixing bugs and writing high performance algorithms. It’s also about creating a great experience for the user and using tools to their full potential.
By taking the time to read documentation with no goal in mind you can discover things about the library you’re working with that you would never realise. Follow your curiosity, it can take you to some great places.
