Even given these many points, I still don’t see serious "confusion" in the D3 v7.5 Ref. Maybe seeing this all in context now will remove some of the confusion that others obviously have. Sure there’ s some old info and typos in there, but the doc is not so critically flawed to preclude development if you know what you’re doing at a higher level.
MV Developers shouldn’t be learning how to use a C interface from a BASIC chapter in a database reference manual. Personally I think all MV environments could use more fundamental information, HowTo’s, examples of business use, code samples, etc. But we aren’t going to find that in a Reference guide which is intended to provide details for people who are already familiar with the base concepts.
If documentation that has been out for so long is so bad that it makes no sense, tell the vendor, whoever that may be. Ultimately this isn’t really about documentation or technical syntax. We’re seeing the effects of poor QA and budget cuts from a company that can’t or won’t pay people who use the software to write or check the related documentation. If this problem is fixed at a business level then we won’t feel compelled or put off by the prospect of reporting every typo or syntactical error through Technical Support.
For what it’s worth, when I got the first cut of the v7.5 Beta docs (User Guide, Ref, etc) I spent a lot of time making notes, and then sent it all back with a note that it was virtually unusable for a number of higher-level reasons. Before the software went production, Raining Data put a lot of effort into correcting as much of this as they could. So I know they were responsive and intent on doing what they could, and I suspect they would put in a similar effort if people just provided them with a list of what needs to be changed.
Unfortunately, rather than reporting issues to vendors, I find many people in this community just have more fun bashing the same piñatas year after year. Hell if we actually told vendors what irritated us, and they fixed it, what would we have to talk (or blog) about anymore?