One thing to consider...
Should we start this Platform spec doc with the 3.0 release? We could still reference the 2.x releases. But, I noticed that this current revision of the Platform spec started with 2.0. This was because we moved from the old microprofile-bom repo to the microprofile repo. But, it provided a nice break due to the Java EE 8 upgrade.
Due to the introduction of the breaking API changes in Metrics 2.0 and Health Check 2.0, should we start over with the 3.0 release in this doc? For this initial RC1, I left it as is. But, since I had thought about it, I'll bring it up to the wider community.
To be clear, I would basically just remove sections 1.2 thru 1.5. I would provide a pointer to the 2.2 Spec, like I currently do. I would just get rid of these extra sections which are a little long and could be confusing since the Required APIs section is where the real meat is... Everything else would stay that same.
-- Kevin