Document the Build Event Protocol API

[steren]

Add documentation related to the Build Event Protocol API (see protos)

Ulf has a change in flight: https://bazel-review.googlesource.com/#/c/3967/

[steren]

We agreed to add proper documentation when we release 0.5.1, which should contain a more stable Build Event Protocol

[buchgr]

In the documentation session at the summit I started to write something up about BEP and BES that could be published as a blog post and link to the design doc for more details. It's not finished yet, but close. Will send out for review next week.

[steren]

The top priority should be to have user documentation. Blog posts and design docs are less important.

[helenalt]

@michelleirvine and @buchgr Can this be completed within the next few weeks, so we could complete the 0.6 Milestone "BEP API is stable", aimed for mid-end August.

[michelleirvine]

@buchgr I'll send you some edits for this file today - sorry for the delay.

[buchgr]

Thank you. Please comment on the pull request and not the google docs.

[buchgr]

Fixed by b4011da