I would pick one place for user-facing documentation, and this file seems like a pretty good one to me.  So I would explain everything here rather than referring to core, which could be a bit scary for some :)