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

Explainers README、既存の explainers、amount.md を確認し、pull request 23 での議論をコンテキストとして使用します。複数の既存の explainers でスコープ外の側面を文書化することを試し、得られたパターンを比較します。この issue で実証的な例を報告し、一貫したパターンが明らかになった場合は 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)