While what we have on https://docs.mamedev.org isn't entirely the best description of how to set a joystick map up, it does pretty much cover the bases.
Nevertheless, our write-up absolutely could use some improvement and that's one of the projects I'm currently working on. I'm borrowing a few bits of your work to improve what we have, so I'd like to say thanks for the permission! I should hopefully have something suitable within a few days at most; the delay is going to be mostly hammering out phrasing a bit.