[racket] How to document a package and access its documentation

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.

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