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

On Mon, Aug 12, 2013 at 11:58 AM, Asumu Takikawa <asumu at 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 <jay at cs.byu.edu>
Assistant Professor / Brigham Young University
http://faculty.cs.byu.edu/~jay

"The glory of God is Intelligence" - D&C 93