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! :frowning_face::frowning_face::frowning_face:

[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"

[Pavel A.]

>"Every variable/parameter representing a physical quantity shall be documented with its unit of measure"

Add this requirement to the AI prompt to generate the manuals ))

 

[Andrew Neil]

but where's the AI going to get it from if the coder didn't put it there in  the first place.

Or are we assuming that the code will also be AI-generated?

[STOne-32]

Dear @waclawek.jan  @Andrew Neil  @Pavel A. @David Littell ,

 

We really appreciate your proposal and suggestions, as you can imagine how many pages we have in our STM32 documentation if we restrict to only Datasheets , reference manuals and errata-sheets among more than  1000+ part numbers. It is among our resolutions for this year 2024 to enhance the pace of updates, and also give you more visibility on documentations errata using this Community as intermediate solution between the confirmation and the publication date. Stay tuned . @Imen.D 

Ciao

STOne-32

[Nikita91]

No need for documentation: have the AI generate the application directly. Like this no more documentation therefore no more errors in the documentation. Artificial intelligence is heralded as more efficient than natural intelligence...

But if the AI has to generate documentation, it will take its sources from what already exists on the WWW, and therefore it will be worse than now!

[Nikita91]

By the way ST documents are not the worse I know. Take a look at those from Expressif (ESP32)...

There is still some communication between users and ST through this forum, and suggestions can be taken into account.

And the ST French/English translation is better than many Chinese/English translations from other providers!