Repository: puppeteer
Issue: [Docs]: Emphasize standard usage vs deprecated in documentation + Usage examples
Labels: feature,documentation,P3

There are multiple parts to this request, and could potentially be split across multiple tickets.

The general sentiment is that the documentation needs to be made more comprehensive, with an emphasis on clarifying "standard usage". Ie: Functions, classes, selectors, etc. where for the average use-case should be considered as the stable first option, as opposed to an experimental/situational alternative. This is attempted [here](https://pptr.dev/guides/page-interactions) and [here](https://pptr.dev/guides/getting-started), but it's vague and contradictory.

For example, on [Page Interactions](https://pptr.dev/guides/page-interactions), the page's landing section is "Locators". This implies that Locators are the primary and suggested means for interacting with the Puppeteer API, yet immediately contradicted by a disclaimer "Locators API is experimental...". Furthermore, when looking at the provided usage examples for Locators, we are given minimal examples of the most basic usage. Improvements that are also needed for this section:

- No visible links to the Locator Class documentation + difficult to find info in actual API docs and not incredibly informative when found.
- No visible links to any documentation for each of the Locator methods used in the provided examples.
- Example "selectors" being used are not indicative of what kind of selectors are compatible, nor are they in line with how they would likely ever be used in a real scenario. Ie: How often is someone going to click `button`? Is this a css selector, an xpath, or am I restricted to clicking elements by their type alone without any granularity in the selector? I can make assumptions, but this needs to be noted or expanded upon.
- `Retrieving an element property` and the `map` method need to be reworked in naming, functionality, and/or provided a description. Does locator return an array of matching elements? In either case, why are we mapping over them/it? Why are we waiting for our map method? Generally `map` returns an array modified by a predicate/callback, so is the returned result an array of booleans, if so why is it called `enabled`? Why is this considered retrieval of `an` element property, when it's implied this is a multi-element operation? Why is this even used at all when there are more concise ways to find whether or not an element is enabled or getting an attribute, ie: `page.$('button:not([disabled[)')` or `buttonElem.evaluate((btn) => !btn.disabled)`.
- `Configuring locators` provides no description of the methods used (apart from what you can infer by their name) and the arguments they take. Why is this api so heavily reliant on chaining together these methods? Is it to avoid race conditions? If so, provide that justification because this method of modifying results (before or after it resolves?) makes it impossible to predefine or modify paramaters set within an object that is external to and used in the function call, disabling use-cases possible in other page methods. 
-  And more...

Just below `Locators` on the same page, we see a section on `Query Selectors`. The description for this states that `Query Selectors` are in fact the primary mechanism for interacting with the DOM on your (Why is a possessive word used here?) site. For being the stated "primary" or standard usage, why is this the shortest and least documented section on this page? Why are comments being used as placeholder descriptions for the page methods used in the code snippet? Why is this the first time we are seeing a verbose CSS selector in use?

Below that is the section of `P Selectors`. This entire section, in addition to the added functionality to puppeteer, should be reconsidered in it's implementation. Starting from the top, lots of buzzwords and not a lot of information - especially for a section so low on the page. First, we get a warning that these "special" selectors are not actually CSS selectors, this is immediately disruptive to the workflow of writing code while referencing dev tools and only adds to the non-transferable learning curve required to learn this new proprietary selector. Why is this even a selector? This string now needs to be parsed out/tokenized, introducing further challenges and overhead. Why can't we just move this to options provided as arguments to the various page methods, modifying the behavior of the selector externally and keeping the CSS selector universally standard? Almost as if the author was losing steam in this section, it includes a grammatical error "... should not be used for actually CSS styling". When "styling" is prefixed by "CSS", it is not a verb, it's a noun. I'm sure i've made a few grammatical errors in this ticket, so please excuse my hypocrisy.

Further down in the same section on `P Selectors`,  we get some information on `>>>` and `>>>>`. Another proprietary format that heavily implies it's own requirement in standard usage, yet it's description and usage are so incredibly niche and confusing. Why are `shadow hosts` discussed in it's usage with this odd assumption that the reader knows exactly what a shadow host is? Given puppeteers "demographic", it's very unlikely they've encountered any such thing. This is then followed by another incredibly niche example that includes a markdown snippet with zero context as to what `<custom-element>`, `<template>`, `shadowrootmode` (and why it needs to be `="open"`), and more. The confusion is even further complemented by a note implying incompatibility of the above snippet with Firefox browsers. There are far too many issues in this section for a GH issue, so i'll conclude it with a question - what do you gain and what are you losing by maintaining this proprietary selector?

Not going to spend much time in `Custom selectors`, but this section could absolutely benefit from it's own page (along with nearly every other section on this page). 

The next section really needs to be addressed, `Query Selectors (legacy)`. Why is this complete duplication of the non-legacy section on `Query Selectors` further up the page deemed as "legacy"? What `prefixed selectors` are being maintained? Do you eventually intend on not maintaining prefixed selectors? If so, how are we to migrate our applications? What is a prefixed selector, and what defines a selector in this context, and why is "selector" seemingly so interchangeable here? Why is type coercion just now being introduced in the Legacy `CSS` section?  Are the `Built-in selectors` actually the `prefixed selectors`? Again, this section should certainly be given it's own separate page - as is the standard for most instances of legacy code documentation.

There are quite a bit of additional, but less significant issues on this page alone. Please put more effort into documentation going forward. This is far from the only page with these kinds of issues, but considering it's introductory nature - I figured it was worth the effort of writing this.