What's the value of efforts towards better documentation?

[waclawek.jan]

Users report here documentation bugs, and Moderators take effort to seek clarification and submit internal tickets. However, these then appear to be ignored.

So what's the point.

JW

[Imen.D]

Hello @waclawek.jan,

We apologize for the delay to correct this limitation.

I will push that for correction in the next release within the Internal ticket number: 173201.

(PS: Internal ticket number 173201 is not accessible or usable by customers).

I truly value your contribution.

[waclawek.jan]

Hi @Imen.D ,

There's no need to apologize, this is not your fault. And this is not the only case, I just came across it accidentally now.

Also, in that thread, it has been noted, that this error goes across many RMs of STM32 containing RTCv2 (which is probably still the majority of all STM32). For example:

I do understand how incredibly hard work is to fix all such details (also read: how much does this cost); but then microcontrollers are all about the details.

So my question here really is, is it worth. Maybe there are other better, cheaper ways - a public, searchable, ST-curated/confirmed repository of such fixes, perhaps? Maybe on this forum, under some dedicated tag (#Documentation probably contains too much other things) / subforum? Think of something like "Errata, lite" - so that users can read DS/RM, then ES for the "hard" errors, and then can go to some list of such "minor" corrections.

JW

[Andrew Neil]

I've made my fair share of criticisms of ST documentation.

But now I have the misfortune to be working with an NXP part - their documentation is the pits! ☹️☹️☹️

[David Littell]

Very sad to hear that.  I loved the old-school Motorola documentation and have seen nothing better since.  It's a shame that they've lost their way in the Moto-to-Freescale-to-NXP transitions.  But true quality writing is in general a thing of the past anyway.

[waclawek.jan]

The complexity of modern mcus is brutal. Individual peripherals exorbitantly complex, a single peripheral such as UART or SPI is way more complex than was the whole mcu three decades ago. And as the cost of masksets is in $M++, it makes sense to pack the kitchen sink together with everything else, rather than to make selectively a set of chips with only those features which are really needed.

So, as we had not just manual/datasheet but also dozens of appnotes per mcu (together with examples), we would need to have dozens of appnotes per peripheral today. But there appears to be a trend to delegate the task to (read: spend money on) clicky generators, which is IMO wrong. It's wrong from the developers point of view; however, they are shiny enough to appeal to the managers, way more than black letters on white paper. Especially, since they come with the promise of final applications churned out at the mouse click, cheap and quick.

And we all know, who holds the money bag, don't we.

JW

#dozens_of_appnotes

[Andrew Neil]

Indeed, although the part I'm thinking of is "just" (sic) an accelerometer ...

[Andrew Neil]

@Imen.D here's another all-too-common fault with ST's* documentation - for physical measurements, units need to be given:

https://community.st.com/t5/stm32-mcus-products/spi-send-sizeof-too-big/m-p/640955/highlight/true#M235821

* Not just ST's, to be fair.

[Pavel A.]

Again, my hopes are with AI. It can be instructed to create a realistic video of dolphins riding bikes, it can be asked to generate documentation for humans, in good English, in clear technical style, with black and white diagrams.

[Andrew Neil]

It does still require the information to be provided in the first place.

It should be part of the Coding Standard: "Every variable/parameter representing a physical quantity shall be documented with its unit of measure"