I also like the comments approach that we use at the bottom of:
https://openacs.org/doc/openacs-4/db-api-detailed.html (for example).
This even gives the opportunity to upload a file, and will make it easier to integrate information with every new release.
The downside is that additional information will not be in one place. Time for a 'DOC Commit' forum, maybe... ?
But, whatever you decide, please give directions here: https://openacs.org/doc
