As I read through the responses and rethink my own response, I want to be clear that my frustration is not, specifically, with information being scattered across so many documents. That’s just natural as documents cover more specific topics that may be generic to lots of platforms (i.e. PRU programming). And I don’t mind sifting through lots of different documents to get additional/updated information. That’s kind of the job and that’s OK when I know the document exists and it’s on me to sift through the mountain of info to find exactly what I’m looking for.
It’s another issue completely when I see from a forum post that a document exists; I even have the name of the document, but I can’t find it on the site that I expect to find it on.
It’s even worse to be new to a platform and have no clue there is additional documentation available that could help me, if I just knew it existed.
I know a big part of web design is to not overwhelm people with too much information. But as an engineer/developer, I’d rather be given all relevant info and allowed to figure out for myself what’s useful and what isn’t. Now where the web designers can help is to organize the data such that the most relevant info is higher in the page, or organized into logical tabs that put the most relevant info in more-left-located tabs and less relevant links deeper in the tab list. But don’t hide the info from me. That’s all I ask.
What would be even more useful is to have documents, like the TRMs, make reference to all these other documents (by name or preferably by link) where applicable. The easiest topic for me to again reference is PRUs, so in the section that talks about the PRU subsystem, let the reader know there are additional resources for the PRU (performance docs, compilers, assemblers, inter-process com technique documents, example code, etc). But even things like UARTs that are configured via registers, if there is more info in the Registers doc, refer off to which doc has that info for more reading. Although if the registers are relevant to operating the UART, I’d rather have that in the TRM, even if it makes the TRM 10,000+ pages. That’s hardly a concern today where everything is digital, and nothing actually printed anymore.
I know there are Technical Document authoring solutions that can help with this. One that comes to mind is AuthorIt. It’s not cheap, but it does let you make topics their own entity (e.g. PRU_ICSS or PRU_ICSSG documentation), and then link those topics into NUMEROUS other documents that all need that info. Then if you ever update/add to that topic, you can automatically reversion & republish all documents that contain that info. I assume TI is using documentation technologies like this. But I’m wondering how effectively they are being utilized. I suspect there are no automated procedures in place to republish updated documents, whether the trigger be when a single topic gets updated or just once a year. I have no problem with keeping my PDFs up to date as long as they are clearly versioned so I can see that I have version 12, but version 18 is now available.
It is also nice to be able to get previous revisions. It’s not something that is used regularly, but sometimes in the process of editing or refactoring documentation, things get removed/relocated…and sometimes those removals are not an overall improvement for SOME documents (but were necessary for others), so being able to get previous versions of a given document is often valuable. Unfortunately, this does require quite a bit of storage space and while this is nice, I get that the cost/benefit ratio often isn’t in favor of doing this. And dynamically re-generating previous revisions from the documentation database, on demand, is also not easy to do or to make secure. But I thought I’d mention it.
It is good to know that there is recognition of these issues and a desire within TI to correct these issues. I also understand that these more modern chips are orders of magnitude more complicated than the chips of the past (e.g. 8096) and their documentation. So it is, somewhat, unfair to compare the documentation for these products to those much simpler offerings. A single Cortex R5F within the TDA4VM is more complicated and requires more documentation than the original 8096. So complicate that by having multiple groups of them, along side multiple A72s, multiple PRU subsystems, and all the other peripherals, the documentation and organization necessary grows exponentially. Then add that this is not the only product TI sells and documents, and the documentation management is absolutely astronomical. I can appreciate this challenge. And I’m quite aware that these challenges will exist for any vendor.
Sorry for the wall of text…