Agreed. Although in hindsight it's rather obvious what I did wrong, when implementing these things in the first place there's little in the way of reliable references. Too often one relies on disassembly of existing code (assuming something can be found) to pick up clues.
That's it in a nutshell - there is no single definitive source of PBI documentation that contains the right mix of factual information from the scant official sources and real-world experiences from the small number of people who have developed working PBI hardware and handler code. The articles that have been written do contain many nuggets of useful information, but to some extent they either suffer from being out of date, or the authors not having been privy to the wider pool of understanding we now have of some of the problems inherent in the bus (e.g. stuff that Hias has talked about in this thread).
A lot of these small details may sit languishing on someone's computer from a project they did, either intentionally because they don't want to share their work or accidentally because they figure nobody else is interested in the details. Or worse yet, they disappear into the sands of time because the only copy gets destroyed or lost in the shuffle over the years.
I've been thinking a bit about what the best format would be for such a thing. A simple document is nice because it's self contained and easy to keep track of a single file - but it's hard to make it a 'living' document where new information can be added by multiple authors. A wiki would be nice because it allows it to be updated with new information as needed, but unfortunately it requires hosting and the long term safety of the data is questionable. We could consider expanding the wikipedia PBI article, but a lot of the material we might want to reference (e.g. the Earl Rice ANTIC articles) is copyrighted, so that's a problem. Ideally we end up with something where new examples and reference code and designs can be tacked on or referenced as people make new projects and are (hopefully) willing to share.
A Google Doc might be good, since multiple people could collaborate on it, but again it has a dependence on their long term hosting and ultimately the file does need to be 'owned' by an individual, and it's hard to make it an Atari community asset.