Re: [racket-dev] Racket documentation
On Tue, Sep 21, 2010 at 5:47 PM, Matthias Felleisen wrote: > > I often program in an 'off line' manner, and I'd find on-line docs to be way > too slow. I don't mind building the docs once a day. Google Gears was a framework to build these sort of things, namely provide locally cached version of a dynamic online service. Google Gears was deprecated but I hear HTML 5 is supposed to have similar functionality, or will have. Alternatively, DrRacket could be programmed to download updates to the docs once a day. _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Racket documentation
Eli Barzilay wrote at 09/25/2010 01:41 PM: Another possibly useful option is to use the local docs and fall back on the remote if they're not installed. This might be a better default -- allowing people to install the local copy and forget about the on-line thing. We don't have to forget about the on-line thing entirely. Even right now, I'd like each page of my local copy of the docs to have a link to the corresponding online page, so that I can continue using my fast local docs but at any time easily give a URL to people. -- http://www.neilvandyke.org/ _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Racket documentation
20 minutes ago, Eli Barzilay wrote: > [...] > 3. And even if you get that resolved, you still have the issue that >Neil raised. That's why I suggested a preference for: >* Using the remote docs.racket-lang.org >* Using a local copy if it's installed >* Using the remote docs if they're accessible, falling back to > local docs otherwise >with the last one being the default. [...] Another possibly useful option is to use the local docs and fall back on the remote if they're not installed. This might be a better default -- allowing people to install the local copy and forget about the on-line thing. -- ((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
I agree with ELi here. On Sep 25, 2010, at 1:21 PM, Eli Barzilay wrote: > An hour ago, Everett Morse wrote: >> Comments on the below discussion and possible implementation ideas. >> >> User-contributed comments should be annotations to the >> documentation. They could then be fetched using JS (Ajax) from the >> local copy when an internet connection is available, > > You mean from the remote copy, right? > > There some major problems with what you suggest: > > 1. Writing JS code that detects if you're connected to the web is, > IME, somewhere between "impossible" to somthing that depends on the > browser, on configuration, and a bunch of other things that just > make it not worth it. (This is all going through "file://" urls > that are extremely restricted that even the current docs are much > less pleasant on IE.) > > 2. Even if you can, you need to face the problem of where the > annotations go. It's not enough to rely on an annotation with a > version range spec -- the actual text that it refers to might > change in a way that will make it anchor in the wrong place or > whatever. (Even url anchor strings change.) > > 3. And even if you get that resolved, you still have the issue that > Neil raised. That's why I suggested a preference for: > * Using the remote docs.racket-lang.org > * Using a local copy if it's installed > * Using the remote docs if they're accessible, falling back to > local docs otherwise > with the last one being the default. There's also a minor privacy > thing with that, but if you get a browser on a remote page, that's > much better than a local file:// page that goes remotely behind > your back. (And that means that option #1 is probably closer to > "impossible".) > > -- > ((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
An hour ago, Everett Morse wrote: > Comments on the below discussion and possible implementation ideas. > > User-contributed comments should be annotations to the > documentation. They could then be fetched using JS (Ajax) from the > local copy when an internet connection is available, You mean from the remote copy, right? There some major problems with what you suggest: 1. Writing JS code that detects if you're connected to the web is, IME, somewhere between "impossible" to somthing that depends on the browser, on configuration, and a bunch of other things that just make it not worth it. (This is all going through "file://" urls that are extremely restricted that even the current docs are much less pleasant on IE.) 2. Even if you can, you need to face the problem of where the annotations go. It's not enough to rely on an annotation with a version range spec -- the actual text that it refers to might change in a way that will make it anchor in the wrong place or whatever. (Even url anchor strings change.) 3. And even if you get that resolved, you still have the issue that Neil raised. That's why I suggested a preference for: * Using the remote docs.racket-lang.org * Using a local copy if it's installed * Using the remote docs if they're accessible, falling back to local docs otherwise with the last one being the default. There's also a minor privacy thing with that, but if you get a browser on a remote page, that's much better than a local file:// page that goes remotely behind your back. (And that means that option #1 is probably closer to "impossible".) -- ((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
There is a privacy/security problem to address: as described, this is phoning home to the mothership, and effectively tracking each user's browsing and searching behavior within the manuals, page-by-page, even though they are using local copies. The tracking situation on the public Web is crazier than even most techies realize, but not many companies put tracking capability into things like local copies of the documentation. Just on principle, I think you wouldn't want Racket to be lowering the bar further, so I think you'd have to address the concern. Everett Morse wrote at 09/25/2010 12:04 PM: User-contributed comments should be annotations to the documentation. They could then be fetched using JS (Ajax) from the local copy when an internet connection is available, -- http://www.neilvandyke.org/ _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Racket documentation
Comments on the below discussion and possible implementation ideas. User-contributed comments should be annotations to the documentation. They could then be fetched using JS (Ajax) from the local copy when an internet connection is available, and if there is no internet connection the annotations simply won't appear. They could be icons on the side (associate each annotation with a function call or some other place marker in a page of documentation) and expand when clicked on. This allows local copies to be as useful as they are now while adding in the community portion when possible. Versioning issues include: - An annotation applies to a specific Racket version, and may at some point no longer apply - An annotation gets folded into the official documentation, so no longer needs to be visible. So each annotation should include a start and end Rkt version number for display to handle the first issue. The second could be handled by setting the end version to expire the comment when adding it to the official documentation (or by some other field if this is a bad idea). Some other emails seem to dislike the wiki approach to documentation. This would then suggest just keeping a list of user comments rather than one chunk of wiki text per documentation location (i.e. per function). This list could be tagged with author user name, or just kept anonymous. Still, even with comments some are more useful than others, so perhaps a community voting system to move the good comments to the top of the list. (Like in Yahoo! questions and many other question-answer forums.) The tie-in to the current documentation is in finding a way to determine Racket version (do we need a separate documentation version number?), documentation page, and functions within the documentation. Then when we display it we just match up the comment lists to the right location in the display. Hopefully that leaves the existing Scribble system untouched, except maybe to add some hints for the tie-in and the JS code to load comments in the local docs. -Everett On Sep 21, 2010, at 11:18 PM, Eli Barzilay wrote: > On Sep 21, Matthias Felleisen wrote: >> On Sep 21, 2010, at 4:58 PM, Eli Barzilay wrote: >> >>> And a side-comment -- having an on-line documentation is probably >>> going to make lots of people who follow the repository happy, >>> since compiling it is where the biggest chunk of time is spent. >> >> No, no. See my comment. The improvements to the docs have to flow >> back to the repository version in some way. > > No, no -- see *my* comment... The improvements *should* flow back to > the repository -- of course -- that's the whole goal. The thing that > I'm talking about in the above is that the default mode for setup is > to *not* build the docs, but the sources are still there -- they're > still being built *if* you explicitly request it, and the nightly > build must do that, since it's generating the on-line version that > everyone sees. > > >> I often program in an 'off line' manner, and I'd find on-line docs >> to be way too slow. I don't mind building the docs once a day. > > To make it easier to read, I'll make the punchline before I proceed to > specify the details of why you won't have any problem. 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). > The best that you'd get is yet another scheme cookbook which will be > left to accumulate binary dust, with very few people who read it, and > very few of them who contribute to it. My guess is that the > percentages were 2% who read the cookbook -- and 2% of the readers > contributed to it (and if I remember the rough numbers correctly, the > numbers of people who contributed was indeed on the order of 0.01% of > the number of users). > > The main point is that if you want real community effort, then you > need *almost everyone* to be aware of it -- both to get more people to > read it, and to get more people to contribute to it. This kind of > interraction just cannot happen in batch mode, with changes getting > through only on new releases, and worse, with participation only from > a few enthusiastics who put in the extra effort to use this community > site. By making it the default you change the first 2% to 90% -- and > the activity around these improvements is now done by 100-200 people > instead of 4-5. > > Back to your problem. Here's how you and others can deal with "I want > to read the docs off-line": > > * A normal user (who wants the released version and nothing else) > downloads the docs, and from then on get to see only that. The only > difference is explicitly asking for the docs to be installed > locall
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
Re: [racket-dev] Racket documentation
On Sep 21, Matthias Felleisen wrote: > On Sep 21, 2010, at 4:58 PM, Eli Barzilay wrote: > > > And a side-comment -- having an on-line documentation is probably > > going to make lots of people who follow the repository happy, > > since compiling it is where the biggest chunk of time is spent. > > No, no. See my comment. The improvements to the docs have to flow > back to the repository version in some way. No, no -- see *my* comment... The improvements *should* flow back to the repository -- of course -- that's the whole goal. The thing that I'm talking about in the above is that the default mode for setup is to *not* build the docs, but the sources are still there -- they're still being built *if* you explicitly request it, and the nightly build must do that, since it's generating the on-line version that everyone sees. > I often program in an 'off line' manner, and I'd find on-line docs > to be way too slow. I don't mind building the docs once a day. To make it easier to read, I'll make the punchline before I proceed to specify the details of why you won't have any problem. 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). The best that you'd get is yet another scheme cookbook which will be left to accumulate binary dust, with very few people who read it, and very few of them who contribute to it. My guess is that the percentages were 2% who read the cookbook -- and 2% of the readers contributed to it (and if I remember the rough numbers correctly, the numbers of people who contributed was indeed on the order of 0.01% of the number of users). The main point is that if you want real community effort, then you need *almost everyone* to be aware of it -- both to get more people to read it, and to get more people to contribute to it. This kind of interraction just cannot happen in batch mode, with changes getting through only on new releases, and worse, with participation only from a few enthusiastics who put in the extra effort to use this community site. By making it the default you change the first 2% to 90% -- and the activity around these improvements is now done by 100-200 people instead of 4-5. Back to your problem. Here's how you and others can deal with "I want to read the docs off-line": * A normal user (who wants the released version and nothing else) downloads the docs, and from then on get to see only that. The only difference is explicitly asking for the docs to be installed locally. * A from-git user uses the the command-line flag to turn on building the docs -- and then you get to use them locally just like the above. * Both users can download the new docs (with some menu entry or something like that) from time to time -- the stable-release user get updated docs without installing a new version, and the git user get updated docs cheaply, with just a download instead of running your own build. This is of course optional. If the first user doesn't do it, they're left with static unchanged docs -- just like now. If the second user doesn't do it, they need to continue paying cpu cycles for building the docs -- just like now. * Another option that would be available is "use the on-line docs if they're accessible". Then you'd get the local copy if you're not on-line. As for speed -- that will not be an issue. By far, the biggest problem now is loading the JS index. If the docs are on-line, then the search can happen on the server side. This is another big benefit: the server side will be some racket code, therefore can do a proper search, including full-text, complicated queries and whatever you want. You'll only pay for the network bandwidth. Even better: *don't* do any searches -- no racket code, no apache proxying, no worrying about server load. Instead -- use the google thing which was raised a short while ago. We get the benefit of a company that makes a living out of doing good search. [Obviously, the docs won't even need to live in the repo like the rest of the sources. For a release-user-with-local-docs there's no difference since they only care about downloading a local copy, how it was built is irrelevant. For a git-user-with-local-docs, this can be done in a similar way to svn externals -- with the docs repo being hooked in the normal repo (in collects/scribblings, for example), so you can still edit them with git.] Eventually, I'd like to see the local docs option used less and less, so the focus can be on improving the on-line version. -- ((lambda (x) (x x)) (lambda (x) (x x))) Eli Barzilay: http://barzilay.org/ Maze is Life! _
Re: [racket-dev] Racket documentation
On Sep 21, 2010, at 4:58 PM, Eli Barzilay wrote: > And a side-comment -- having an on-line documentation is probably > going to make lots of people who follow the repository happy, since > compiling it is where the biggest chunk of time is spent. No, no. See my comment. The improvements to the docs have to flow back to the repository version in some way. I often program in an 'off line' manner, and I'd find on-line docs to be way too slow. I don't mind building the docs once a day. _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Racket documentation
On Sep 21, Eli Barzilay wrote: > [... lots of stuff that he'll be happy if even two people read ...] > [as usual.] The only concrete suggestion that I see here is the following. How practical it is is debatable. I'll try to make this short enough to be more effective than the previous post. * Drop the documentation from the default setup. Make it an optional step instead. Don't even include the .scrbl files in the released installers. * Make all the documentation tools (DrRacket, `help', etc) use the local documentation pages *if* they exist. Otherwise use the on-line version straight from the server. * Package the documentation as an optional file, which people can install if they want to. I know that there's a lot of schools that will want that -- so perhaps there should be some organized way to do this. Maybe some `raco get-me-a-local-copy-of-the-docs' command, or maybe some (simple!) gui dialog that can be used to do this -- simple enough to be implemented now, and later grow to the "choose additional packages to install" thing that is planned anyway. * On the other side of these schools, I think that most day-to-day Racket hackers would not see any difference, since many are probably using the on-line version anyway. (I know I do, if only to see the official version that everyone sees...) So for these people the result is going to be positive -- no need to install a ton of files, no need to translate `file:///some/dir/on/my/machine' to `http://docs.racket-lang.org/', no need to build the documentation. Together with this, there should be more awareness of the documentation being something more dynamic, and therefore start talking about older versions when such changes are relevant. That's probably the iffy part that makes it a harder pill to swallow. Like I said -- IMO the benefits are obvious and desirable. One thing is that fixing the docs is going to have an immediate effect -- you complain about a typo, I fix it, and the next day it's fixed for "everyone" (except for those that choose to install a local copy, of course). The questionable part is in the fact that Racket can move fast in some areas -- fast enough that writing version-independent documentation is pretty difficult. This needs some better solution -- maybe some back-door place where older versions are kept which is relevant for things that are more than N releases old. For example, I redesign some library and write it from scratch -- I shove the old documentation there, and the updated version will say "if you're using Racket v.N and below, go [here]". But this should be the exception, since most documentation work is improving things in general, and most "things" don't move that fast. Once that's in place, the download-the-documentation thing could use the updated version -- so I can update my documentation even if I keep the same racket version. Maybe there should be some way to give me all of the documentation pages that are relevant for my version, so I'll stop getting updates to some revised library if I don't have it. Also, when it's in place, it would become practical to talk about some on-line annotation thing, as I sketched in the previous post. Practical to make it doable as some kind of a server thing or whatever. -- ((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
[Sorry, I planned on some short and concrete description, but ended writing a blog-post-like piece of text... FWIW, I would love it if someone takes this on seriously.] On Sep 21, Everett Morse wrote: > I had some thoughts about Racket's documentation compared to PHP's > last night, so this morning I wrote up a blog post about it. > [...] You have some good points there, IMO. There are several problems with the current state of the Racket documentation, on top of a whole bunch of very good things with it. The good thing with it is the separation between "guides" and "references". When you look at a piece of functionality, there's always a tension between explaining it to newbies (and in this context "newbies" is anyone who doesn't know about a particular functionality, so it includes everyone -- not just people who are new to the language as a whole), and writing a detailed and accurate reference. Having both guides and references mean that a documentation writer is free of this tension -- and write exclusively in one of the two modes. But the bad thing is that there's not enough connectivity between the two documents (I'm thinking of the reference and the "Guide" manuals), and somehow the links between them are not obvious enough. (This is judging by reactions, since I rarely read the guides when I'm looking for information.) Improving that should be a welcome goal. Another problem is that there's not enough guides -- for most random libraries there's just a reference and no investment in a proper guide. In some cases a guide that provides a high-level view of a library is sorely missing -- jumping right into the reference can often miss important questions like "what needs does this library fill?". There are also cases where a guide is not really needed, since the library is more narrow and there's no need for a high level/intorduction kind of view. But most frequently, and this is a meta-level problem, there's a need to write a single piece of documentation -- then water it and let it grow for a while: add more high level description at the top of the library's page, then grow that to a full section, then add some subsections, and then decide to split the whole thing into a guide and a reference. This whole transition is very hard to do -- mostly because the initial documentation is written by the library's author -- and the author is constantly in a race to improve things, add features, redesign things, etc -- and the documentation is often a second class citizen in this whole activity. In some cases the documentation doesn't change at all. New functions are added, of course, but then they're documented "reference style", and the high-level parts are rarely changing. Worse: such changes often wait for the author -- who is not only busy with working on the code (and in the Racket case, it's often "codes") -- but in addition, the author doesn't have a good high-level perspective on a certain library. They *know* what it is for -- since it was *their* itch that started the whole thing -- but it's very difficult to put yourself in the shoes of some random hacker who is new to the library. So, IMO, a good solution is exactly what Matthias suggested. It's really best if there is some place to have everyone contribute to improving the docs. This doesn't even mean editing the sources directly: just a place for user-comments would be enough. A place where you can ask questions, answer questions, suggest revisions, give general hints, or write your own mini-tutorial -- even if it's only one function that you're writing this tutorial for. (There's no shortage of single functions or small function clusters that could have their own tutorials -- there's probably enough people on this list that have taught in classes and know that something like `fold' could really use a tutorial, not to mention things like `current-custodian'...) As for the technical details, there are some problems to overcome. The first thing is presentation. It could work best if there was some way to have some split view (maybe something like the google side-bar thing) where people can do this kind of interaction. It should be some wiki-like editable thing, where a library documentation writer can participate in the discussion -- for example, see a question and answer it by improving the docs for that question. But this is the easy part... I see two hard parts on top of this, both are related to making this kind of communication work. * On one side, there is the interaction between the people who use the side-bar thing (whatever form it has) and the documentation writer/s. It would be nice if there was a way to put alerts on these things -- so, for example, I document `foo' and whenever someone uses the system I get an email telling me that there was a comment there. It would also be nice to be able to have these alerts for the people who write the comments -- if I ask a question, I'd like the syst
Re: [racket-dev] Racket documentation
Jay McCarthy wrote:
What do you think is missing from these tutorials:
http://docs.racket-lang.org/quick/index.html
http://docs.racket-lang.org/continue/index.html
http://docs.racket-lang.org/more/index.html
In particular, Quick tries to present the essence of the languages.
Maybe the problem is that since we are PL researchers, we have a more
refined opinion about the "language" versus the "libraries" so our
tutorials don't go too deep in the libraries.
We like languages and libraries factored so we can reason about them in
isolation; users like them integrated so they can understand how they're
used together. OTOH, with hygienic macros, all languages but the kernel
language are libraries anyway, so maybe we should stop fooling ourselves
that there's a well-defined difference in the first place. :)
We need more examples in the docs. It's easy to add them and I will
help anyone who wants to get involved.
I agree with Matthias that this is something best done by non-core
developers. I think it would be great to have some of it done by
trustworthy casual users as well. How hard is it to give easy access to
docs for the most basic functions without giving access to the source
itself? I imagine these (along with I/O and other peripheral libs
necessary for solving ``real'' problems) would be the most important to
flesh out.
Is there a way to reduce the barrier so far that you don't even have to
check out and compile Racket to contribute to the docs? And additionally
not have to remember very much to remember how to do it?
It lists related functions. You may be looking for something similar to the
function you found. This listing helps you compare similar functions and
hone in on the one you really want.
This is a good idea, but I think it is a symptom of the one-page per
function, whereas in Racket they are listed together with related
ones.
I think they should stay that way. Interaction among functions is too
important to put a click barrier on. Separating them would be like
putting each method doc on a different page for an OO library.
Occasionally it warns (with appropriate font and colors) about common
gotchas, like when something has changed from one API version to another
(e.g. a function now returns false on failure instead of -1), or when some
environment needs to be set up right (e.g. setting a timezone before calling
the date function, it even tells you what function sets the timezone).
See above with the ad-hoc grossness of PHP.
I agree it's less ad-hoc in general, but it *would* be nice to have a
uniform way to indicate functionality *extensions*. ("Hey! Two versions
ago, we added an optional 'bip' argument to 'bop'!" Or "You should
really consider using scale/improve-new-text in place of scale in general.")
---
One thing I'd like to see institutionalized is having two different
descriptions: a "high-level" one, and a "here's the nitty-gritty
details" one. I've been put off using functions before because of those
details, especially functions that deal with syntax. Later I found out
that the function was exactly what I needed. Even later I found out that
the detail was extremely important in solving a problem in an important
common case. The whole thing could have gone a lot faster with two
descriptions.
I know that would happen somewhat if there were always examples, but it
wouldn't guarantee it.
Neil
_
For list-related administrative tasks:
http://lists.racket-lang.org/listinfo/dev
Re: [racket-dev] Racket documentation
On Tue, Sep 21, 2010 at 1:14 PM, Everett Morse wrote: > I had some thoughts about Racket's documentation compared to PHP's last > night, so this morning I wrote up a blog post about it. > > Here is the link: > http://www.neptic.com/blog/2010/09/how-to-design-documentation/ > > Below, for your convenience, is the complete text copy-pasted in. > > Thanks, > -Everett > > > > How To Design Documentation > > We’ve been using a programming language called Racket in our lab, and one of > the new guys is constantly complaining about its documentation. Everyone > agrees, but we argued a bit about what language has good documentation. Here > is one that I missed in that discussion; I will explain why PHP is a model > citizen. > > Background > > I learned to program at the age of ten from books on BASIC Level II using a > Radio Shack TRS-80 (black and white). At twelve, my dad gave me a book on > Java, but it was written to help a C programmer learn Java. So I read a book > on C for BASIC programmers, then immediately dumped C and learned Java. I > read many more programming books after that, mostly about Java. The net > result is that by my senior year in HS I had a solid background in Java with > basic understanding of C, C++, and Javascript. > > How I learned PHP > > At that point I heard about PHP as a website programming language, and > decided to learn it. Whereas with Java, C, and BASIC I had read books, with > Javascript I had learned rudimentarily by just copy-paste-edit. So I began > with copy-paste-edit on PHP too. But I also read one of those “Getting > Started” / “Five-Minute” tutorials, which helped because of my background in > Java. > > That got me started, but from then on I constantly referred back to the PHP > online documentation, and over the course of one job (about eight months) I > gained a solid understanding of PHP just from using it with the > documentation. > > What Racket Has > > With Racket, no short tutorial is going to work because it has a LISP (and > Scheme) functional programming background that is foreign to most new > programmers and many experienced ones. What do you think is missing from these tutorials: http://docs.racket-lang.org/quick/index.html http://docs.racket-lang.org/continue/index.html http://docs.racket-lang.org/more/index.html In particular, Quick tries to present the essence of the languages. Maybe the problem is that since we are PL researchers, we have a more refined opinion about the "language" versus the "libraries" so our tutorials don't go too deep in the libraries. > It does, however, have a good sized > guide that can get someone into the language well enough. They also have > searchable, browsable documentation of every function in the entire API. > However, that API documentation, while complete, is usually so cryptic or > vague that it is useless. I’m sure if you understood Racket well it would > all make sense, but it does not help a beginner get better. > > What PHP Does > > PHP has a whole page for every function in its API. The page describes the > function parameters, lists all the options, and describes the possible > output. But here is what more it does: > > It describes corner cases, like what happens when empty string is passed in, > or what happens if the right environment is not present. My gut tells me that this is needed in PHP because it as more ad-hoc cases rather than the elegant purity of Racket. My gut also tells me that this is a biased position. > It gives examples for almost every function. It is often easier and faster > to skim the function description, then read the examples to learn how it is > used. This makes more sense than trying to parse some description, > especially easier than parsing the grammar-like definitions of Racket > functions. We need more examples in the docs. It's easy to add them and I will help anyone who wants to get involved. > It lists related functions. You may be looking for something similar to the > function you found. This listing helps you compare similar functions and > hone in on the one you really want. This is a good idea, but I think it is a symptom of the one-page per function, whereas in Racket they are listed together with related ones. > Occasionally it warns (with appropriate font and colors) about common > gotchas, like when something has changed from one API version to another > (e.g. a function now returns false on failure instead of -1), or when some > environment needs to be set up right (e.g. setting a timezone before calling > the date function, it even tells you what function sets the timezone). See above with the ad-hoc grossness of PHP. > Finally, at the bottom of the page is user comments. Here friendly people > can ask all the common dumb user questions that help out everyone else who > also had the same dumb question. (So dumb the documenters didn’t think it > worth explaining.) People also tend to arrive at the same place looking for > certain functionality, and
Re: [racket-dev] Racket documentation
Everett, thanks for your comments. I think they are right on: On Sep 21, 2010, at 3:14 PM, Everett Morse wrote: > I’m sure if you understood Racket well it would all make sense, but it does > not help a beginner get better > You may not believe this, but even someone who has programmed in Racket for 15 years and in DrRacket for 13 of them, the API docs are still quite cryptic :-) > What PHP Does > I like what you describe. Most or possibly all of what PHP provides should come with Racket too. Here's our problem. We need manpower to get from where we are to where we should be. Here is what I see could happen: 1. Scribble our doc language needs some escape hatch into a wiki. I think Eli has thought about such things and others probably, too. The web server is in Racket, so that's taken care of. 2. The existing docs have a huge advantage over everyone else's docs. I am sure you know that. So the challenge is to integrate (1) with the existing Docs. Not a big deal and doable. 3. The sources, including docs, are all out there. Take them. Change the layout. Equip each function/method page with a user-wiki-thingie. Collect suggestions, appoint editors, edit the suggestions into the doc pages. 4. There's no need to host this internally initially. When the thing is off the ground, we integrate it and -- minus the wiki -- localize it. The wiki becomes a link to the on-line version of the docs (corresponding page) and then users who find they have something to contribute are one click away from doing so. I think this is a wonderful project that non-core PLTers can run and they would make a huge contribution to the language and community that way. ;; --- > With Racket, no short tutorial is going to work because it has a LISP (and > Scheme) functional programming background that is foreign to most new > programmers and many experienced ones. And that's the reason I welcome your ideas so much. It is possible to program in a Lisp-style language as if you were in C plus parens. Hey we have for/do and if and assignment statement, and we have classes. But yes, you'd lose a lot if you adopted this style. It wouldn't make sense to run things that way. But the API idea is fascinating. Someone step forward and pick it up. We'd welcome it. Thanks for such a wonderful idea -- Matthias _ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
