Re: priorities, as with the style-insensitivity debate, there is a **_strong
selection bias_** in who one hears from (maybe stronger, actually). People @jtv
mentioned who find docs lacking and immediately give up do not hang around to
weigh in on project priority debates. It's hard to say how much people who do
participate account for outside perspectives (or maybe those of people they
have helped shepherd). { The two relate incidentally in that Zed Shaw was
offering teaching/course material for changing the default to be
style-sensitive. } This isn't to say anyone thinks there is a silver bullet,
adoption-wise. Popularity is a fickle mistress.
To be more constructive, doc problems hit skill layering quickly..maybe faster
for Nim with people coming from both beginner/Py-like languages who need to see
DEBUG BUILD & kooky languages like C++/Rust with such clues traditionally
absent. Skill/background assumptions drive level of detail for all
writing/learning. Assumptions about go-to-def skill (of machine|man) even play
a role.
Doc layering helps with bigger skill level ranges. The Unix `man` system has
(at least) 5 levels: command/proc ident itself, one-line apropos "summary for
search", synopsis, overview, full detail. The levels usually come in that
order. So, you start reading & continue if you seem to be understanding/it
seems relevant/you need to know more. Not sure it's best to put _too_ much
right at impl definitions..but separation can lead to doc-impl divergence, but
people do like hypertext view staging.
To end really concretely, a one-liner "apropros"-like intro automatically
included in [The Index](https://nim-lang.org/docs/compiler/theindex.html) might
really boost discoverability over in-page searching for idents/types in the
stdlib. E.g., the "first blank row separated block of text in any doc comment
is the "pithy summary". Almost the default structure as-is. Maybe this has been
suggested before?
Doc layering/staging also takes discipline (like Nim's standardized GithHub
Issue template) as well as work sourcing since few enjoy doing it. So,
trade-offs all around, but I think it could help many if someone added the
"pithy summary" feature for something like The Index and some other(s) to do a
real thorough pass over the documentation. This has happened-ish before with
`runnableExamples:`, but as with all things (everywhere, not just Nim!) is
incomplete. There are surely many places with single-hash regular comments that
could be converted to doc comments..e.g. the first 3 lines of [this
one](https://github.com/nim-lang/Nim/blob/version-1-6/compiler/sigmatch.nim#L802)
(selected more|less at random..).
