[racket-dev] current packages' docs, errors, and conflicts

On Tue, Jul 8, 2014 at 8:14 AM, Matthew Flatt <mflatt at cs.utah.edu> wrote:
> At Tue, 08 Jul 2014 14:08:27 +0200, Jan Dvořák wrote:
>> On Tue, 2014-07-08 at 12:46 +0100, Matthew Flatt wrote:
>> > The rightmost column of the table may need some explanation. The column
>> > highlights conflicts among names of package-installed executables,
>> > foreign libraries, and documents. Currently, all the conflicts are
>> > document names, because several packages have a documents named simply
>> > "manual" or "main".
>>
>> Can you provide some guidelines on docs naming?
>> I am responsible for half of the conflicts. :-)
>
> A package "X" that provides a collection "X" of the same name should
> probably also call its documentation "X".
>
> If the package provides both "guide" and "reference" documentation,
> then "X-guide" and "X-reference" are good choices.
>
>
> Thanks for looking into this! I've recently updated the Racket
> documentation, but I expect that more is needed. As far as I can tell,
> nothing in our documentation previously suggested that documentation
> names needs to be distinct.

Is there a reason we can't just make this work with duplicate names
instead? Perhaps disambiguiating by collection name?

I think this would change all the current URLs on
docs.racket-lang.org, so we'd have to fix that, but it seems better to
make us do a fixed amount of work rather than push this coordination
problem onto everyone who writes packages in the future.

Sam