[bazel.build] Suggestion on Target Visibility documentation improvement

[PaulRashidi]

Page link:

https://bazel.build/concepts/visibility

Problem description (include actual vs expected text, if applicable):

When it comes to reading documentation on Bazel's visibility feature, IMHO, most devs are going to be in one of two modes: 1. Figuring out how to open up the visibility correctly 2. Setting up their project with good practice.

I think the docs could read slightly faster by having the target visibility docs suggest the better practice norm that every BUILD file declare a default visibility in the package rule at the top and override it within the lower rules, when something should be exposed. Most notable, just showing a 10 line BUILD file example with export_files, package, and a go_lib rule with a few comments about what would be visible.

As it is right now, the fact that default_visibility can be configured in the package state is within the second page of content on Target visibility, but even there the wording assumes you're versed in Bazel and know what the the package declaration is and where to find out what it's fields are so you can properly declare.

Also of note, showing devs a good simple norm on package groups would be nice as well. IMHO, the documentation is perfectly correct, but may not quickly address the most common use case of reading the documentation. It could have a "quick examples" section which assists in perpetuating the better practices without requiring devs to go to StackOverflow (which doesn't have many BUILD examples yet). Even if those quick examples pointed directly at files within GitHub.

Where do you see this issue? (include link to specific section of the page, if applicable)

https://bazel.build/concepts/visibility

Any other information you'd like to share?

No response