How do you test your documentation? Properly test it, ensuring that it answers many kinds of questions for those who are new to the topic, and who haven't already been working on this project for months?
If you're not testing it, then how can you consider it done? Would you do the same with your software?
The vast majority of documentation that I see these days is bad in multiple ways. Most common is lack of coverage for important topics or cases, and I'm not even talking about things like "why this product is built this way".
I'm talking about stuff like:
- An API providing all kinds of methods for manipulating "Fribblers", and when you look at the Fribbler class it just says "This is the primary class representing Fribblers." No idea what this means or how it fits into the wider API? Good luck!
- Parameters or properties appearing in lists without any explanation of what they mean
- ... and that's assuming those parameters are even listed at all, which (often) they're not
- ... especially when those parameters appear in other parts of the documentation. "This method will work asynchronously unless you've passed the "borgle" attribute to the Fribbler constructor." There's a borgle attribute?!
- And this is all just for basic usage of a product. Want to contribute, or run tests, or anything else? Nothing.
Documentation needs usability tests, same as anything else which is primarily designed to be used by humans who may not have seen it before. But it's hard enough getting proper UX testing for the product, let alone its documentation.