Agreed On Sun, May 3, 2015 at 7:17 AM, Neil Van Dyke <[email protected]> wrote:
> 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. > -- 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/CAFp0D54EQ0x3dOiM%2Bxh%3DvSbD_0a%3D1yMwY8%3Dzq%3DAcb4KXAfPoXQ%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
