Adding some clarification about the use of --out=json and the output.

Regarding issue #1685 I've added some clarifying text to the docs to ward off additional questions about the subject. If we have it here, at least some will see it and save themselves some time.