There's a lot that is mistakenly conflated as "documentation".
Sometimes I would know enough about a topic except for one little thing and would look to the documentation. I only needed information on that one little thing to be productive, but I'd get stuck reading someone's entire backstory, trying to skim and find the one useful line in a random example to help me.
Other times, I would find documentation and struggle to follow it in practice until I came to the conclusion that I would need to read the whole thing in its entirety to become productive. I would either have to block out some time to learn it all or go with a completely different solution.
I used to think projects that claimed to be documented either fit into two groups:
1. Good documentation: I can find what I'm looking for
2. Bad documentation: I can't find what I'm looking for
There isn't just good documentation and bad documentation, there are 4 different kinds of documentation for distinct types of information delivery: Tutorials, How-To Guides, Explanations, and finally Reference.
Now I consider documentation good or bad based on if it contains all 4 kinds of documentation.
There's a lot that is mistakenly conflated as "documentation".
Sometimes I would know enough about a topic except for one little thing and would look to the documentation. I only needed information on that one little thing to be productive, but I'd get stuck reading someone's entire backstory, trying to skim and find the one useful line in a random example to help me.
Other times, I would find documentation and struggle to follow it in practice until I came to the conclusion that I would need to read the whole thing in its entirety to become productive. I would either have to block out some time to learn it all or go with a completely different solution.
I used to think projects that claimed to be documented either fit into two groups:
1. Good documentation: I can find what I'm looking for
2. Bad documentation: I can't find what I'm looking for
My eyes were opened when I read something that I have since committed to memory: https://documentation.divio.com
There isn't just good documentation and bad documentation, there are 4 different kinds of documentation for distinct types of information delivery: Tutorials, How-To Guides, Explanations, and finally Reference.
Now I consider documentation good or bad based on if it contains all 4 kinds of documentation.