Looking for Ideas for the Package Overview Page on OCaml.org

Community
50

Ok, so that was quite a bit to digest. Here’s a summary:

1- Debate about package quality metrics

Having “last published” and publication date in general displayed on the page might interfere with the visibility of stable packages that do not need improvement.

Ideas for other metrics:

  • (manual) self-assessment of package author. (Code quality, performance, maintainability, evolution, version >= 1.0.0 etc.)
  • (manual) Maintenance-related tagging: signal the need for additional maintainers, signal that a package needs maintenance
  • (automated) Signal broken packages.
  • (automated) Metrics from external sourecs: e.g. GitHub Number of issues / pull requests / star count
    • Contrapoint: supporting all options, including popular open source self-hosted optionsis a huge work item, and choosing just a few is inherently unfair
  • (automated) Weekly download statistics

2- Debate about displaying or not displaying README / opam description / index.mld on package overview:

  • Since README is publicly displayed on GitHub/GitLab etc, many people currently use it as a “public landing page” of the package.
    • Essentially, these other services encourage writing README in a certain way - in order to establish proper context within that other service
  • Challenge: Ideally, package authors should not have to repeat the same info in several places.
  • Aspects to consider wrt README:
    • different renderers on different sites (e.g. GitLab, GitHub, SourceHut, Pygments, etc.) support different markdown features
    • Nowadays more and more READMEs contain images or even videos, as well as tons of badges
  • Ideas:
    • Show a collapsible README on package overview
    • Instead of rendering README on package overview: add a link to the README (but where to, to the hosted repository or to ocaml.org’s rendition of README?)
  • Index.mld and other .mld files could be displayed instead of README. Additionally, links for API documentation and tutorials
    • Note: if you don’t specify an opam synopsis and/or description yourself, dune-release derives those from your README as described in Looking for Ideas for the Package Overview Page on OCaml.org - #40 by dbuenzli. However, when you want to link somewhere from within the $(DESCRIPTION) block, that will not work at the same time on GitHub as well as in other documentation contexts (e.g. locally-built offline documentation vs ocaml.org vs GitHub).

3- Playground functionality

  • “Tested examples”, i.e. ability to write code sections in the package docs that will be executed as tests during the documentation build - helps package users assess whether the documentation is up to date and makes it easier for package authors to update the docs when functionality changed
  • Ability to run code examples from packages in the playground
  • “Runnable examples” like Testable Examples in Go - The Go Programming Language - ability to write code sections in the docs that will (1) run as tests during the package documentation build step, and (2) render as an “inline-playground” within the surrounding documentation page

4- Other Feedback/Ideas

  • Allow URLs like https://ocaml.org/p/{PACKAGE}.{VERSION}
  • On package version dropdown - Add published date for each version
  • Security advisories / report package vulnerability
  • It would be nice to have badges for your package to display on the README so that the package repository looks attractive on the version control website where it is hosted
  • Package overview should show all the findlib library names
  • Dependencies, Reverse Dependencies and Conflicts need more space, as they can be quite narrow and tall

5- Package overview pages inspiration

11 Likes