Just a suggestion, which seems like a lot of work...
Does anyone think it would be a good idea to merge the Guide into the
Reference, so that there is no longer a Guide? (Any supplemental
tutorials would remain separate.)
Examples of how users would use documentation then:
* Someone who is doing documentation searches would always get sent to
the Reference, where they could scroll around to get gentle/introduction
as well as technical detail. (They wouldn't have to
understand/decide/find whether they were going to the Guide or the
Reference, nor land in one document and not realize that there is
counterpart info/text they cannot see. This one still gets me
frequently, even though I have a pretty good sense of what's in the
manuals, and sometimes, like just now, I have trouble getting search to
get me to the right manual when I'm pretty sure I know which one I want.)
* Someone who is navigating to identifier documentation from IDE would
likewise go to the Reference, like above user.
* Someone new to the language might start by reading whatever
tutorials. (We don't confront them with deciding between tutorials,
Guide, and Reference. And tutorials would link to parts of the
Reference, for more info. Tutorial information would generally be
redundant wrt the Reference, unlike the Guide is now. When tutorials
are not redundant wrt Reference, such as might be the case for some
syntax extension mechanisms, maybe that info should actually be in the
Reference.)
* Someone new who'd already been through some tutorials and wanted to
get a better sense of the scope of the language would navigate the
Reference. Gentler/introductory bits like are currently found in the
Guide would appear in appropriate places in the Reference, so reader
could see both the introductory and the detail easily.
* Some new but who likes to skip tutorials and inhale documentation (as
is not too uncommon) would skim/skip through the Reference, like the
above user.
Note that, with the Reference subsuming the Guide, the authors of the
Reference don't necessarily need a hard distinction between "guide mode"
and "reference mode" when writing. (The "reference mode" isn't always
so formal anyway.)
Neil V.
--
You received this message because you are subscribed to the Google Groups "Racket
Developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/racket-dev/55455AF8.10405%40neilvandyke.org.
For more options, visit https://groups.google.com/d/optout.
