On quality of MCU documentation

[danielholala]

Hello,

please excuse my rant but I have to vent my thoughts:

Comparing the newer LPC553x reference manual to the older LPC552x user manual, I noticed that the quality of the documentation has deteriorated regarding format and content.

The reference manual is less reader-friendly. There's no more coloring und underlines for headers, the tables are inflated with padding and increased line spacing. The new format and style increases the total page count from 1200 to 2200 while not providing more information (both devices provide a similar set of functions). 

Regarding content, the reference manual is sparse on explanations and often too brief instead of explaining a feature and showing how it fits into the bigger picture. Sometimes the reference manual uses examples from which the reader has to deduce information (information which rather belongs in the main text). Furthermore, all acronym and respective concepts should be thoroughly explained, and memory addresses should be printed clearly.

By way of example, take  "CMPA". The user manual spells out the acronym, spends more than  a full page to describe the concept and lists its memory addresses prominently:

The reference manual, though, does none of these things: The acronym is not spelled out, the concept of this memory area is not explained and its memory address is hidden in example code.

Please NXP, improve your documentation and make NXP great again.

[diego_charles]

Hi @danielholala 

I am sorry for the delayed response! 

I have been discussing your feedback internally and we want be sure to thank you for your feedback and let the door open to receive more inputs from you and the community. 

The NPI team explained to me that many of the changes are made because of  formatting,  which is to allow our reference manuals to be updated and maintained easier than what we had in the past. The infrastructure that is used for documentation requires a certain format, so most newer devices will have this format compared to older devices which followed a more manual method which made it a bit difficult to maintain. 

This is all in effort to make the user experience better in all senses. A ticket to the doc team to  have the details of CMPA spelled out, will be submitted definetely. It is done in the security reference manual of LPC55S3x, but for some reason was not in the regular manual.

For other content if you require a more detailed explanation, please provide what sections are lacking so we can help them get the information but in addition improve the documentation.

I do appreciate your effort reporting this,

Diego

[danielholala]

Thank you, @diego_charles , for your open-minded response. I'll gladly point to more content in the LPC553x reference manual that I I think should be improved.

Section 48.1.4: 

"Enable VREF module (PDRUNCFGCLR0[PDEN_VREF] = 1) in PMC register. DAC PTAT and ZTC current sources comes from VREF module.". 

Section 48.7.1.5 Global Control (GCR) does not explain the difference between PTAT and ZTC and why to choose one over the other (or enable both). Again, the acronyms should be explained. Note: regarding temperature drift, I'd always select a zero temperature coefficient source over a proportional to absolute temperature source but it's just an educated guess that this is true for the two different current sources provided by LPC553x.

Section 47.3.4:

 "Asynchronous input sources at the periphery of the module can generate hardware triggers."

In my opinion, the reference manual should be more elaborate on the concept of configurable hardware trigger sources. The explanation in section 47.1.6. "There are four trigger sources for each ADC module. ADC Trigger sources get routed through the Input Multiplexer (INPUTMUX). See the INPUTMUX chapter for available trigger sources. See registers ADC0_TRIG[0-3] and ADC1_TRIG[0-3]." is not sufficient to explain the concept.

Further, the reference manual should provide links to the two INPUTMUX registers (as it does on other occasions).

Also, the bits in INPUTMUX registers regarding trigger sources are not explained at all, see section 14.5.1.21.
For example, the register ADC0 Trigger input connections (ADC0_TRIG0 - ADC0_TRIG3) lists, among others,  "T4_MAT3", "PWM0_SM0_MUX_TRIG0" or "AOI0_OUT0". I can do an educated guess but why not add a sentence to each entry in the list of bits to explain them?

Section 28

Unfortunately, the ROM API does not use self-explanatory method names. As such, it is the responsibility of the documentation to explain how the API methods work together. However, the reference manual fails to  explain, e.g., why "ffr_cust_factory_page_write" is the corresponding API to "ffr_get_customer_data". The documentation of the former method refers to "CMPA", while the latter does not use this term but rather “Customer Factory Page”. The combination of bad API naming and bad documentation leaves the reader confused. Further, the manual does not point out that to write successfully to the CMPA, the transfer size must be the size of the CMPA. This is relevant if you want to use "blhost.exe" tool to write to CMPA.

Lastly, I'd like to point to suggestions made by @scottm regarding the use of undefined acronyms and concepts there in this community.

Thank you for your attention to this matter.
Best regards,
Daniel

[diego_charles]

Hi @danielholala 

Thank you again for your comments, It is good to have them. 

I alreay shared them back to the team. 

Diego

[diego_charles]

Hi @danielholala 

Just to let you know, the team received your feedback and they will work to improve the user manual.  At this moment I can not promise a date, as it not longer on my hands. 

Thank you very much,

Diego

[danielholala]

Thanks @diego_charles , I hope that the time invested into these postings will be worthwhile. I just want to let you know that it's not the first time I complained about the quality of the LPC553x reference manual. I wrote about it as early as 2023 ("on DAC current sources") but I'm afraid not much improved since then.

Keep up the good work.
Cheers
Daniel