I often complained about documentation...until I had to write the technical manual. I discovered it isn't nearly as easy as it seems. Writing a manual after the fact means you have to recall all the design criteria that was never written down and lay it out in a manner that's hopefully easy to comprehend. And when you finish, there's no one to edit it, because you're the only expert.
Grammar and spelling checks help, but they do miss glaring errors. So you proofread, except you miss the errors because you've seen the text so many times the words blur together. Your mind skips past those spelling errors.
On the whole I've found ST reference manuals to be very helpful, other than a few cases like their arcane USB. The Cube tools are a nightmare, so much that I never used them. Doxygen used on the old ST Peripheral Library was great for some internal code documentation but worthless to anyone but the programmers who wrote it in the first place.
I've used ST controllers since the ARM7TDMI, before the Cortex series. The old SPL Library concept worked well until ST decided to be clever and package a "one size fits all" code generation package that does little more than encourage migration to Linux and A series. I'm sure this made economic sense so I can't criticize ST for business decisions. It does impose a technical debt in that the firmware embedded in a project is no longer maintainable solely by developers. I'm not willing to pay that price, since I staked my expertise and reputation on the product I delivered to my employer (not to mention the massive headaches it causes in regulated industries).
As for the bad attitude in general, I had one of those "AH HA" moments when a Windows app programmer told me I was wrong to comment code because the functionality should be self-evident based on how the variables were named. He was taught to do this at university. Writing is drudgery, coding is exciting. Until, of course, your manager hands you that brilliant code with the assignment to maintain it, since Cowboy Coder has left for some flavor of the day website.
To answer your question, have patience and be grateful for whatever you get for documentation. The days of the ten foot high stacks of OS/360 or the "gray wall" of DEC VMS documentation died forty years ago. If you're lucky the worst you will encounter are spelling errors. Does anyone remember when ST changed one of the STM32F4 pins from Vcc to GND between versions of the datasheet? Those kinds of documentation "features" are the ones that should keep you awake at night.
Jack Peacock
