Simplify documentation about tags

[AlexSkrypnyk]

Is your feature request related to a problem? Please describe.

As a reader, I find it very difficult to grasp how to name and use tags and if there is any special handling required reading this docs page Documentation about tagging tests

Other frameworks (like PHPUnit) allow to provide tags in a form of @mytag. Bats has it is unique way, which is probably driven by some technical challenges, and it understandable. But the documentation is written in a such way that a reader need to read the whole page to understand how to use the tagging feature, and even after that - it is still not clear on some specifics.

1. Starting from the first example:

# bats test_tags=tag:1, tag:2, tag:3
@test "first test" {
  # ...
}

Is tag: in tag:1 a special keyword? Should my tags start with tag:? If not - can it be just mytag? (It can!) What is the significance of the colon :?

2. No example for bats:focus
   Should I write it as # bats test_tags=bats:focus? or # bats bats:focus or # bats:focus?

3. No example of multiline tags. Can I do this?

# bats test_tags=mytag
# bats test_tags=myother
# bats test_tags=mythirdtag
@test "first test" {
  # ...
}

4. Not clear if the path to a file containing a tag should be specified.
   Should it be bats --filter-tags mytag or bats --filter-tags mytag path/to/file

Describe the solution you'd like

1. Update docs to use real life examples instead of overloaded tag:1 or a:b.
2. Restructure the docs section so it is easy to grasp how to use this feature for 80% of cases ( i.e., have all the relevant information in the first paragraph or two with all edge cases described later).

Describe alternatives you've considered
N/A

Additional context
I've been using bats for 5 years and still forget this syntax. I can only imagine how people using Bats occasionally gets confused by these docs.

[AlexSkrypnyk]

Could be as simple as having a "quick reference" subsection at the very beginning:

---

# mytest.bats
# bats test_tags=mytag
@test "first test" {
  # ...
}

Run only tests tagged with mytag:

bats --filter-tags mytag path/to/file

[martin-schulze-vireso]

I am all for better documentation but don't have the capacity for that right now. I am more than happy to accept PRs though. 😉