As discussed in #1347, the documentation lacks a bit of context - while we're still considering other improvements in this area, we want to ensure that this is properly documented.