Why developers hate documentation
Original Email March 28, 2025
Reading docs is boring 🥱
Understanding docs is hard 😣
Writing docs is even harder 😫
There are a load of reasons for this. Some of my personal favorites are:
A lot of times, you're in a hurry to fix something. Taking 5-15 minutes to read docs to fully understand how things work can feel unproductive. Especially when googling, watching a video or asking AI can usually lead you to an immediate answer.
Reading docs can feel overwhelming. There's usually a lot of information to go through and new concepts to learn, which brings up loads of questions. In what order should that information be consumed? Which concepts are key to learn first?
That's why details like how the documentation is structured, how good the search is, and whether there's a "start here" page make the experience a lot easier. If we see something akin to a roadmap, suddenly it becomes less scary.
Reading and understanding documentation is a skill. It might not feel like it sometimes, but it is. But depending on your background, previous experiences, and strengths, learning in general could be easier or harder for you. It takes focus, patience, and relating past knowledge with the new information to learn effectively.
I wrote in an email once that knowledge is relational to our previous experiences. We also learn sequentially. Because docs are written sequentially, the author is deciding on the sequence in which we should learn concepts. But that sequence might not always be the optimal way you could learn.
The documentation isn't written well a lot of times. Or it's outdated. Or it's missing important information or details that we need to solve a particular problem. It can be missing good examples. That can be annoying.
Writing documentation is really, really hard. Writing is a skill in itself. In fact, it's a skill nobody teaches us. There are best practices for writing good documentation. Small things like deciding what's important to know, what isn't and creating an outline go a long way.
Writing documentation is very, very boring. It's not coding. It's writing about the concepts and details around our code. It's the opposite of fixing problems. It's describing the already existing solutions. Boooooring. (Thankfully, AI is excellent for this 😉)
Alternatives to documentation, like watching videos or asking AI questions, are a lot more fun and engaging compared to reading documentation. I am super guilty of this myself, despite knowing that the documentation in many cases is the best, most updated source of truth of what I'm working with.
Speaking to the last point on this long list,
I know this documentation is sometimes the BEST thing because... I took a very long time to check out the newest React docs 😅
I have been absolutely blown away by how good the examples, explanations, and concepts have been ironed out in the new version. Especially since the last time I checked it out (which was a few years ago). So much so I think I might sit down soon and talk about it in one of these emails to write about my experience and what I learned 🙂
In the meantime, you can read a tiny bit of my thoughts on the React docs here.
As always, thanks for reading, and have a wonderful weekend!
In my opinion, one of the biggest reasons that developers and software engineers hate to do documentation is that when you are in the workplace, completing documentation does not check off any metrics boxes for upper management and therefore your own job security if there is any. They usually care about features completed and direct problems solved. Often doing documentation is perceived to "take away" from feature development time.
i also hate the docs because it is really boring but i think we need to build a habit to start reading docs so i am reading minimum one two docs or blogs everyday now i thinks reading docs can make us a good learner