guide and reference
60 views
Skip to first unread message
Neil Van Dyke
May 2, 2015, 7:17:14 PM5/2/15
to Racket Dev List
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.
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.
WarGrey Gyoudmon Ju
May 5, 2015, 2:26:16 AM5/5/15
to Neil Van Dyke, Racket Dev List
Agreed
--
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 racket-dev+...@googlegroups.com.
To post to this group, send email to racke...@googlegroups.com.
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.
Greg Hendershott
May 8, 2015, 1:15:50 PM5/8/15
to Racket Dev List
I like this idea, too.
I think the existing syntax/parse documentation is a good example of
how this can work well. It has an excellent introduction, numerous
examples, and then it gets into explicit reference material. It seems
natural to have this grouped together, in that order, and it's very
helpful.
http://docs.racket-lang.org/syntax/stxparse.html
p.s. Yes, I'm acting like one of the animals in that parable where the
chicken wants to make bread. None of the other animals volunteers to
plant the seed, harvest the wheat, and so on. But they're all willing
to help eat the bread!
But I like the idea!
I think the existing syntax/parse documentation is a good example of
how this can work well. It has an excellent introduction, numerous
examples, and then it gets into explicit reference material. It seems
natural to have this grouped together, in that order, and it's very
helpful.
http://docs.racket-lang.org/syntax/stxparse.html
p.s. Yes, I'm acting like one of the animals in that parable where the
chicken wants to make bread. None of the other animals volunteers to
plant the seed, harvest the wheat, and so on. But they're all willing
to help eat the bread!
But I like the idea!
Jens Axel Søgaard
May 12, 2015, 2:04:55 AM5/12/15
to Neil Van Dyke, Racket Dev List
2015-05-03 1:17 GMT+02:00 Neil Van Dyke <ne...@neilvandyke.org>:
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.)
Depends on how. The Reference is huge - a rewrite will be a huge undertaking.
With less effort I think we should consider adding overview pages.
An example from the Mathematica documentation:
Also we lack more tutorials (in the same styles as the existing three).
/Jens Axel
Reply all
Reply to author
Forward
0 new messages