doc: reword some BUILD File advice.

It used word "publish" misleadingly, so I fixed that.
While I was in there, fixed up some kooky grammmar.
And Patrick spotted some obsolete stuff, so clean that up, yay.

Bugs closed: 486, 687

Reviewed at https://rbcommons.com/s/twitter/r/1355/
Sync of https://github.com/pantsbuild/pants/commit/15c9cd5e29e7577175c272cb9c3013aa0db4d6f1