The code is the documentation often

The code is the documentation often

(disclaimer: I work for Intel but don't speak for Intel nor do I speak about Intel below; my comments are generic and from a broad experience outside Intel in a previous life)

It's nice to request documentation for hardware, some people do it politely, others try to use unfriendly ways such as verbal abuse or blackmail. And for many things, documentation is actually available. If you look at it, most things that have good driver-writer documentation available are those which are around for a long time, with slightly different revisions over time (e1000 is such an example from Intel, other companies have similar examples; especially in the server/enterprise space you will find this kind of hardware with good docs).

However that's only one half of the story. For many pieces of hardware, no such driver-writer level documentation exists! At all. Often the driver (often only the Windows one) gets developed together with the hardware, and the driver ends up BEING the documentation. (sometimes there is a document that claims to be documentation but is utterly useless for writing an actual driver from; and often even that doesn't exist).

Theo and others can jump up and down the vendors throat all they want, but what doesn't exist doesn't exist. No amount of begging, pleading, violence, threats and PR changes that.

In addition, with a consumer product shelf life of 3 to 6 months, companies that make such consumer electronics usually don't want to waste the time (and time to market) to create detailed and good enough documentation. And once the product is on the shelves, they're no longer going to care, they know it's gone in 3 months so spending resources is only a waste of money. That's not bad will, that's simple economics of the cutthroat market. Again the server space is better for this, and you'll see companies care more there.

Now it's not all bleak: there is documentation! Just not in the traditional PDF form. It exists in the form of source code that is released for, say, Linux. If you're lucky that is. The sucky cases are when there isn't any open driver at all (hi Nvidia). Let me repeat that: A good open source driver is usually worth 100 times more than the shoddy PDF that's called "documentation"; if it exists at all.

A note about your webcam example: Even the best and most open driver-documentation will have tables like "to make this work, put these 20 values in the registers". Sometimes a vendor can explain what each value means, but often it's just a case of "these 20 worked and we tested that. anything else we don't know". It's nice to know each individual value and what it means, but reality is that often an individual value has no meaning on it's own. This is especially true for calibration and such settings, but often also for cases where multiple analogue components work together.