Re: [racket-dev] Racket documentation
Eli Barzilay wrote at 09/22/2010 04:30 PM: On Sep 22, Neil Van Dyke wrote: I think that you can make online docs sufficiently immediate value-added that people are drawn to use those. I don't believe that this will ever be effective enough. We have a large number of newcomers (because it's being used in courses there's a constant stream of new students who later move on), and these people will never see it. Can't the the online version can't be the default? Just don't somehow break the local-copy for the people who want it, is all I'm asking. It's OK if the local-copy docs require some savvy to get to. (Also, when used in developing nations and such, online might not be an option.) -- http://www.neilvandyke.org/ _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Racket documentation
Don't talk it to death with long emails. Help people to get this started. -- Matthias On Sep 22, 2010, at 4:30 PM, Eli Barzilay wrote: > On Sep 22, Neil Van Dyke wrote: >> Eli Barzilay wrote at 09/22/2010 01:18 AM: >>> The punchline is that your desire to use a local copy is in direct >>> contradiction with the desire to get community involvement in >>> improving the docs. No matter what facility is available for the >>> community to discuss and supplement the docs -- if you have to go >>> out of your way to see it, then you (the collective) just won't do >>> it (statistically speaking). >> >> I think that you can make online docs sufficiently immediate >> value-added that people are drawn to use those. > > I don't believe that this will ever be effective enough. We have a > large number of newcomers (because it's being used in courses there's > a constant stream of new students who later move on), and these people > will never see it. Also, IMO if you need to choose to use some > alternative, then many people will never bother doing so, and many > people will not do it because they'll want to stick with a blessed > version. > > >> This can be done without compromising local-copy docs. If you did >> the online right, everyone knows that they get immediate benefit >> from the value-add of the online docs, so they must have a good >> reason when they use local copy. > > Specifically, you don't have to have any reason if it's the default. > > >> Whatever you do, I hope that the goodness of well-edited local-copy >> docs is not compromised. > > I'm imagining having the docs with an easy way to see the user > contributions/discussions/suggestions -- and the improvements to the > actual docs would be done continuously based on this feedback. > > >> Also keep in mind that some of us think that, when working on >> library code or documentation, the interface should present both >> code and doc easily. Usually, with dumb tools, that means >> JavaDoc-like embedded documentation. I have a goal to make Racket >> support this better in the future, and I hope that any new online >> docs thing won't get in the way, and that I can be compatible with >> that. > > Yeah -- that would be an issue of the doc sources are in a separate > place. Doc sources that are in code (like a javadoc-like thing or a > literate programming thing) will have to stay there. > > But given the overall excitement around this, I doubt that anything > will happen. > > >> I think that some of the problems that the Scheme Cookbook encountered >> are relevant to Racket. [...lots of issues with that wiki...] > > These are all true, but they'd been much better still if there were > more people involved. If you think about everybody that uses racket > having a (prominent) one-click access to the content, you get orders > of magnitude more eyes, and this can lead much better to a > self-organizing wikipedia-like effect. > > -- > ((lambda (x) (x x)) (lambda (x) (x x))) Eli Barzilay: >http://barzilay.org/ Maze is Life! > _ > For list-related administrative tasks: > http://lists.racket-lang.org/listinfo/dev _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Racket documentation
On Sep 22, Neil Van Dyke wrote: > Eli Barzilay wrote at 09/22/2010 01:18 AM: > > The punchline is that your desire to use a local copy is in direct > > contradiction with the desire to get community involvement in > > improving the docs. No matter what facility is available for the > > community to discuss and supplement the docs -- if you have to go > > out of your way to see it, then you (the collective) just won't do > > it (statistically speaking). > > I think that you can make online docs sufficiently immediate > value-added that people are drawn to use those. I don't believe that this will ever be effective enough. We have a large number of newcomers (because it's being used in courses there's a constant stream of new students who later move on), and these people will never see it. Also, IMO if you need to choose to use some alternative, then many people will never bother doing so, and many people will not do it because they'll want to stick with a blessed version. > This can be done without compromising local-copy docs. If you did > the online right, everyone knows that they get immediate benefit > from the value-add of the online docs, so they must have a good > reason when they use local copy. Specifically, you don't have to have any reason if it's the default. > Whatever you do, I hope that the goodness of well-edited local-copy > docs is not compromised. I'm imagining having the docs with an easy way to see the user contributions/discussions/suggestions -- and the improvements to the actual docs would be done continuously based on this feedback. > Also keep in mind that some of us think that, when working on > library code or documentation, the interface should present both > code and doc easily. Usually, with dumb tools, that means > JavaDoc-like embedded documentation. I have a goal to make Racket > support this better in the future, and I hope that any new online > docs thing won't get in the way, and that I can be compatible with > that. Yeah -- that would be an issue of the doc sources are in a separate place. Doc sources that are in code (like a javadoc-like thing or a literate programming thing) will have to stay there. But given the overall excitement around this, I doubt that anything will happen. > I think that some of the problems that the Scheme Cookbook encountered > are relevant to Racket. [...lots of issues with that wiki...] These are all true, but they'd been much better still if there were more people involved. If you think about everybody that uses racket having a (prominent) one-click access to the content, you get orders of magnitude more eyes, and this can lead much better to a self-organizing wikipedia-like effect. -- ((lambda (x) (x x)) (lambda (x) (x x))) Eli Barzilay: http://barzilay.org/ Maze is Life! _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Racket documentation
And also, the wiki software kinda blew in many ways. One of the biggest ways was a small thing with, I think, big implications: the software would by default add an attribution line for each edit, encouraging people to view the page as a dumbed-down Web commenting forum to append a comment to, rather than as a coherent document to refine holistically. Also, depersonalization can be good: when there are no authorship names at all on a page, some people will have less resistance to making improvements. This also removes some of the incentive to contribute for some people, which can cost the document some good contributions but also scare off some low-quality contributions (see, as cautionary tale: Java sites). I think that removing incentive alone is not a net loss, and that depersonalization overall is a big net win. Neil Van Dyke wrote at 09/22/2010 03:53 AM: Eli Barzilay wrote at 09/22/2010 01:18 AM: The punchline is that your desire to use a local copy is in direct contradiction with the desire to get community involvement in improving the docs. No matter what facility is available for the community to discuss and supplement the docs -- if you have to go out of your way to see it, then you (the collective) just won't do it (statistically speaking). I think that you can make online docs sufficiently immediate value-added that people are drawn to use those. This can be done without compromising local-copy docs. If you did the online right, everyone knows that they get immediate benefit from the value-add of the online docs, so they must have a good reason when they use local copy. For a simple example of docs similar to Racket's can be online and participatory to some degree, see PostgreSQL's. They have their well-structured and well-edited manuals, and online you can browse a version with old-school community annotations at the bottom of each page. I've found some of the annotations very helpful, and I'd hope that they feed future versions of the well-edited manuals. You could also go more of a Wikipedia route. But you don't have a million contributors, and you will be spending lots of effort on quality control, and with a relatively small contributor pool you have to be more cautious about alienating people when a contribution really needs to be excised. Whatever you do, I hope that the goodness of well-edited local-copy docs is not compromised. Also keep in mind that some of us think that, when working on library code or documentation, the interface should present both code and doc easily. Usually, with dumb tools, that means JavaDoc-like embedded documentation. I have a goal to make Racket support this better in the future, and I hope that any new online docs thing won't get in the way, and that I can be compatible with that. The best that you'd get is yet another scheme cookbook I think that some of the problems that the Scheme Cookbook encountered are relevant to Racket. One is that a few characters of Perl operators from some Perl Cookbook item, in the Scheme Cookbook could become a huge page full of different verbose, cryptic, and so-so quality attempts to do a comparable thing in Scheme. (Which, in hindsight, should not have been surprising, when Schemers are involved.) I finally decided that most of the cookbook entries would ideally mostly be pointers to reusable code libraries (*not* copy&paste&munge), which led to me to silly extremes like: http://www.neilvandyke.org/tabexpand-scheme/ There were also various quality control problems for various reasons. I got disenchanted after realizing that messes were being created faster than good content, and that it would've been much easier for me to do something correctly from scratch than find a politic way to fix an existing entry or wrestle with the wiki software to reverse some bizarre structure change some user had done. (This is actually much like software development in general.) A problem that the Racket online docs *won't* necessarily have is that of scope: as I recall, the Scheme Cookbook was originally mostly PLT-specific, and some dork (me) advocated strongly that the Cookbook cover other Scheme implementations (e.g., R5RS whenever possible, then separate out the various implementation-specifics within an entry). This turned out to be additional mess and bulk. Racket will still have to decide what to do about version differences, but any mess will be a lot smaller and simpler to organize. -- http://www.neilvandyke.org/ _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Racket documentation
Eli Barzilay wrote at 09/22/2010 01:18 AM: The punchline is that your desire to use a local copy is in direct contradiction with the desire to get community involvement in improving the docs. No matter what facility is available for the community to discuss and supplement the docs -- if you have to go out of your way to see it, then you (the collective) just won't do it (statistically speaking). I think that you can make online docs sufficiently immediate value-added that people are drawn to use those. This can be done without compromising local-copy docs. If you did the online right, everyone knows that they get immediate benefit from the value-add of the online docs, so they must have a good reason when they use local copy. For a simple example of docs similar to Racket's can be online and participatory to some degree, see PostgreSQL's. They have their well-structured and well-edited manuals, and online you can browse a version with old-school community annotations at the bottom of each page. I've found some of the annotations very helpful, and I'd hope that they feed future versions of the well-edited manuals. You could also go more of a Wikipedia route. But you don't have a million contributors, and you will be spending lots of effort on quality control, and with a relatively small contributor pool you have to be more cautious about alienating people when a contribution really needs to be excised. Whatever you do, I hope that the goodness of well-edited local-copy docs is not compromised. Also keep in mind that some of us think that, when working on library code or documentation, the interface should present both code and doc easily. Usually, with dumb tools, that means JavaDoc-like embedded documentation. I have a goal to make Racket support this better in the future, and I hope that any new online docs thing won't get in the way, and that I can be compatible with that. The best that you'd get is yet another scheme cookbook I think that some of the problems that the Scheme Cookbook encountered are relevant to Racket. One is that a few characters of Perl operators from some Perl Cookbook item, in the Scheme Cookbook could become a huge page full of different verbose, cryptic, and so-so quality attempts to do a comparable thing in Scheme. (Which, in hindsight, should not have been surprising, when Schemers are involved.) I finally decided that most of the cookbook entries would ideally mostly be pointers to reusable code libraries (*not* copy&paste&munge), which led to me to silly extremes like: http://www.neilvandyke.org/tabexpand-scheme/ There were also various quality control problems for various reasons. I got disenchanted after realizing that messes were being created faster than good content, and that it would've been much easier for me to do something correctly from scratch than find a politic way to fix an existing entry or wrestle with the wiki software to reverse some bizarre structure change some user had done. (This is actually much like software development in general.) A problem that the Racket online docs *won't* necessarily have is that of scope: as I recall, the Scheme Cookbook was originally mostly PLT-specific, and some dork (me) advocated strongly that the Cookbook cover other Scheme implementations (e.g., R5RS whenever possible, then separate out the various implementation-specifics within an entry). This turned out to be additional mess and bulk. Racket will still have to decide what to do about version differences, but any mess will be a lot smaller and simpler to organize. -- http://www.neilvandyke.org/ _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
