For "quality of written documentation", It would be interesting to hear the views of the audience here.
When I first started with STM32xx in 2016 I was warned by friends that the STM documentation is massive, disorganized, voluminous and takes years to read.
It's certainly voluminous, but that's a consequence of the amazing capability of the series. How long would it take you to write a manual describing 37 Peripherals, 413 Registers and 3044 bitfields ? and that's just for a lowly STM32F0xx! Writing error free documentation for these MCU's is a massive task.
After a few months of flailing around I started to get a grip on the STM and ARM document system and now it's my preferred documentation, personally I now prefer it to any other I've seen for any other MCU . I find the usual 4 or 5 documents for every STM32xx comprehensive and easy to read, usually going for the "technical reference" first.
I have this to say to STM for their documentation ... "Bloody good job STM, keep up the good work"
I confess, documentation is a sore spot for me. I "grew up" in embedded design during the 90s when chips were far less complex. Documentation is undoubtedly a much larger task nowadays than 30 years ago, but documentation isn't the only chip-design task which scales with complexity, so I don't see how mfgs get a pass here. My contention is that documentation hasn't really kept up. 90% of my work is with STM32, and IMO their documentation is about as good, or maybe better, than their competitors'. The problem is that *nobody* has great documentation.
Just now I fetched a couple of old (print) databooks: The Dallas Semiconductor "Soft Microcontroller" (a flash-like non-volatile 8051 before flash was available), and the Motorola DSP56000 family manual. I was going for the Motorola 68000 family manuals but I must have thrown them out already. But anyway, it's mostly the era, not the particular vendor or part, that matters. Pick up any one of these books, thumb to a page of dense prose, and start reading. In most cases it will be clearer, more concise, and less ambiguous than what we have available for contemporary parts. This is not mere pedantry or old-age grumpiness! Many times I will read a paragraph in an STM32 Reference Manual, go back and read it again, and still not be 100% sure what the author is trying to say. This makes my development effort measurably less efficient. Besides ambiguity, another symptom of poor writing is wordiness, so as impressive as those thousands of pages of documentation are, you'd probably have 5% fewer pages (wild guess) if they were actually written well.
I chalk this up to several trends:
1) I suspect semi mfgs have not hired tech writers in proportion to the amount of documentation they produce. Much of ST's documentation is clearly written by ESL people, and while I have great admiration for those who speak multiple languages fluently (compared to my pitiful ~ 1.17 languages), tech writer is not a career I would expect for a non-native speaker. As an example, the DFSDM chapter in the STM32L4 Reference is written by someone from India, whereas other sections of the same manual have obvious China-isms.
2) English is the first language of vastly fewer engineers in the 21st century than it was in the 20th.
3) Of those who do speak/write English as a first language, English proficiency has steadily fallen. All you have to do is compare the written output of college freshmen in the US over time. The change is dramatic! See also: engineering graduates whining about all of the "useless" liberal-arts courses they were required to take in school
4) Semi mfgs have convinced themselves that their crappy libraries (CubeMX etc) are actually the preferred way for engineers to use their products, therefore they probably believe the detailed documentation is less important. Already in areas outside MCU-land, we see chips where the mfg requires use of their own driver software, while register-level documentation is only available under NDA or not at all.
Some of these are not bad things. For example, the increasing dominance of India and China in the tech sector has certainly accelerated innovation, and I imagine that outstrips any "documentation tax" that we pay as a consequence. But it should still be pointed out, and I wish mfgs paid more attention to the quality of their documentation. Unfortunately, one of the consequences of #3 is that native speakers' reading comprehension has also decreased, and many of them are in management, so the decision makers are increasingly blind to the problem.
Home
Help
Search
Login
Register
