[explainers] How should an Explainer describe out of scope aspects?

Esamina il Explainers README, gli explainers esistenti e amount.md, usando come contesto la discussione nella pull request 23. Sperimenta documentando gli aspetti fuori ambito in diversi explainers esistenti e confronta i pattern risultanti. Il lavoro è completato quando vengono riportati esempi empirici in questa issue e, se emerge un pattern coerente, vengono documentate le linee guida nel README.

Explainers start with a description of user problem(s) to be solved. Depending on the problem(s), the boundaries of what to solve or not may be unclear, or solutions for subset(s) of the problem(s) may be significantly simpler or more practical than solutions for the full possibilities of the problem(s).

We should document a way (or ways) for Explainer authors to explicitly communicate what they consider out of scope for a particular Explainer, either by description or specific example(s).

For example @martinthomson noted that currencies may not meet the documented criteria for solutions for the amount explainer.

Here are a few ways to document such out of scope aspects:

1. A brief “Out of scope: (inline list of examples and/or classes thereof).” sentence at the end of section 1, to explicitly communicate what problems the explainer is not trying to solve
2. A brief "Out of scope: solutions that (inline list of undesired characteristics, dependencies, or classes thereof)" sentence or paragraph at the end of section 2, to explicitly communicate what kinds of solutions the explainer is not exploring
3. Rephrasing the out of scope aspect as a caveat of a proposed solution, and adding that to section 8 caveats, shortcomings, etc.

A good next step here would be some amount of experimenting with adding out of scope aspects to existing explainers in this repo, then commenting on this issue with those empirical examples. If good patterns emerge, we can document them as explicit guidance in our Explainers README.

(Originally published at: https://tantek.com/2024/222/b1/explainers-describe-out-of-scope)