On Mon, Aug 12, 2013 at 11:58 AM, Asumu Takikawa <as...@ccs.neu.edu> wrote: > On 2013-08-12 09:51:49 -0600, Jay McCarthy wrote: >> We could make it so you could have that link on the >> server too, but I'm skeptical >> that the lack of one redirection would be very compelling. > > If I understand correctly, you're suggesting that developers upload > their docs to their github repo and users just follow the link to the > package source and look for the docs.
No, I'm not suggesting that. We already have a plan for how the package catalog will show documentation: by building the real documentation and showing it. You said that you don't want to wait for that and want something else as a stop gap. I agree with all your problems with this stop gap, which is why I intend to implement the original idea. Jay > > Several downsides I see with this scheme: > > (1) How will the user know that there may be documentation in the > package source repo? (currently most packages do not have any) > > (2) Even if there are docs, they're not in a consistent format or > place. For example, it could be a link from the repo page, > could be in-lined into the README, or stashed somewhere else > in the repo. > > (3) The user won't know in advance for any specific package if > there is or isn't documentation until they click through. > Since the docs could be anywhere, the user has to search > the entire repo page with the hope of finding something. > > (4) On the developer side, it's important that pre-built docs > are easy to set up. There's currently no "canonical" way > to do this (I have been using Scribble's markdown output, > Stephen has another way, etc.). > > PLaneT made it really easy to shop around for packages by looking at > docs. It would be great if we had this for the new package system too. > > Cheers, > Asumu -- Jay McCarthy <j...@cs.byu.edu> Assistant Professor / Brigham Young University http://faculty.cs.byu.edu/~jay "The glory of God is Intelligence" - D&C 93 ____________________ Racket Users list: http://lists.racket-lang.org/users
