While we're (sort of) on the subject of badges on pkgs.racket-lang.org: the
"This package needs documentation" badge is mostly great, both as a
producer and consumer of packages.

I've encountered at least two types of cases, though, where packages may
intentionally and justifiably lack documentation (or at least not have it
in a form that pkgs.racket-lang.org can recognize):

   - Packages that are split up into "foo"/"foo-lib"/"foo-doc"/"foo-test".
   The server doesn't know that "foo-doc" documents "foo-lib", so packages
   like "foo-lib" get the "needs documentation" badge. For example,
   "gui-lib" gets the badge.
   - Packages that just distribute platform-specific native binaries, like
   "ffmpeg-x86_64-win32". It's a bit more complicated in this case to
   generalize where the documentation is, and it is certainly at least
   arguable that there should be some sort of documentation of the existence
   and purpose of such packages, but it would probably be very silly to give
   each one its own "scribblings/ffmpeg-x86_64-win32.scrbl" as the package
   server expects.

Giving these kinds of packages the "This package needs documentation" badge
seems less than ideal for package consumers: I'm probably not the only one
who avoids depending on undocumented packages. Most of the time, of course,
it isn't too confusing given a moment's thought (assuming one knows the
-lib/-doc/-test convention and/or the maintainer filled in the
"description" field), though there do seem to be some native binary
packages that are not obviously linked to their client package(s), but even
a momentary stop-and-think impedes quickly scanning or programmatically
filtering the search results.
There's another downside for package maintainers, which is that these show
up as "todos". While, again, maintainers probably don't have to think much
about it when they actually review them, the existence of
intentional/expected "todos" prevents maintainers from applying the simple
rule that nonzero "todos" always means there's something they should go and
fix.

I think the most useful resolution would be to give package maintainers a
way to specify that some package documents or is documented by some other
package (or possibly some arbitrary URL—I would have reservations about
that approach, but it seems worth considering whether it might be useful
for the case of native binary packages). Other options I can imagine, like
adding a way to just suppress the badge, seem less good in that they would
weaken the badge system.

This is a post and not a pull request because it seems like there are a lot
of details that would need to be agreed upon, and I'm not sure I know the
right answers or all of the non-obvious implications. (For example, should
the documented package point to the documenting package, or vice versa, or
should both packages have to "agree" on the relationship?) If consensus
emerges, though, I would be happy to contribute some implementation effort!
(Eventually …)

-Philip

On Sun, Mar 25, 2018 at 1:02 PM, 'John Clements' via Racket Users <
racket-users@googlegroups.com> wrote:

> I’m fixing problems related to documentation on the libgit2 package, and
> it appears there are a number of issues to fix, but the first one was that
> the package was written with a main scribblings file called “manual.scrbl”.
> It turns out this is a bad idea, and in fact this is mentioned in the raco
> documentation, and there’s a helpful “conflicts” file that appears in the
> “Most Recent Build Results.” (Unfortunately, I didn’t find this until I’d
> already figured out this part of the problem.) My question is this; have we
> given any thought to adding a conflict notification—either a badge or an
> entry in the green box—to the front pkgs.racket-lang.org page?
>
> Apologies if there’s some good reason this isn’t already a thing.
>
> John
>
>
>
> --
> You received this message because you are subscribed to the Google Groups
> "Racket Users" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to racket-users+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Reply via email to