The Problem
2024 Stack Overflow survey listed technical documentation and written tutorials as two of the top three resources for learning to code.
Despite this I’m sure you’ve experienced (likely more than once) that frustrating moment when you finish reading a tutorial or documentation and feel even more confused than when you started.
This can be a serious problem because poor documentation and tutorials can discourage developers from learning or adopting a certain technology.
Evidence
Actually in 2017, GitHub's Open Source Survey showed "incomplete or confusing documentation" to be the top pain point. I doubt the situation has significantly changed since then, at least judging from my personal experience and experience of others with whom I have interacted.
Possible Causes and Solutions
One possible cause, in my opinion, is that we as developers need to realize that writing is a separate skill and it needs to be worked on to be improved.
You can be an excellent coder but still struggle to explain your ideas clearly in writing. So if we, as developers, work a bit on this skill, maybe we can improve the situation a little bit.
For example in academia, it's well understood that being an expert in a subject doesn't automatically make someone a good teacher. The same principle applies here.
Organizations can also help improve the situation by:
- regularly gathering feedback from developers who use the organization's documentation, and making improvements accordingly.
- adding technical writers to support documentation efforts.
- paying more attention to documentation related issues on GitHub repositories, which, in my experience, are sometimes overlooked.