Reference Flexmailer in CiviMail documentation
"FlexMailer (org.civicrm.flexmailer) is an email delivery engine for CiviCRM v4.7+. It replaces the internal guts of CiviMail. It is a drop-in replacement which enables other extensions to provide richer email features."
Flexmailer has fairly comprehensive documentation here: https://docs.civicrm.org/flexmailer/en/latest/ but it is not mentioned in https://docs.civicrm.org/dev/en/latest/framework/civimail.
Given that Flexmailer is designed to be the future of mail in CiviCRM, and the place where developers should be focusing their efforts (rather than hacking CiviMail) we should reference the flexmailer documentation in https://docs.civicrm.org/dev/en/latest/framework/civimail and let people know that they should focus their efforts there.